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The HP-UX Technical BASIC system runs on the HP-UX operating system. It is a robust BASIC 
language, containing a generous complement of capabilities. 

This guide describes how to develop Technical BASIC programs. It covers the range of topics 
from designing algorithms through writing advanced BASIC programs. Before getting into the 
technical details of the system, however, you can benefit from looking at what is in this chapter 
and in this guide. 

Chapter Contents 

This chapter covers these topics: 



Tasks/Topics 


Page 


Prerequisites for using this guide. 
A description of what's in this guide. 


1-2 
1-4 
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Prerequisites 

Here are the prerequisites that you must meet before using the HP-UX Technical BASIC system: 

• Hardware must already be installed. 

• Both HP-UX and Technical BASIC software must already be installed. 

• Previous experience with HP-UX (or UNIX 1 ) and BASIC will be helpful, although not a 
formal prerequisite. 

Hardware Installation 

All hardware must have already been installed. If not, refer to the installation manual for your 
model of computer. 

Software Installation 

The HP-UX system and the Technical BASIC system must have already been installed onto your 
disc. If the BASIC system is not already installed, refer to the HP-UX manuals for your particular 
system. 

HP-UX Knowledge 

Although this guide assumes that you have had some previous programming experience and a 
knowledge of UNIX or HP-UX, you need not have a high level of skill in either area. 

In order to use Technical BASIC on the HP-UX operating system, you should be familiar with 
the following topics: 

• How to log in and out of HP-UX (relevant only with multi-user HP-UX systems). 

• How the HP-UX file system is structured. 

Background information on using HP-UX can be found in the the manuals supplied with your 
HP-UX system. 



UNIX is a trademark of AT&T Bell Laboratories 
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BASIC Knowledge 

This Programming Guide discusses only the Technical BASIC language; it does not describe using 
the Technical BASIC system. For instance, it describes writing programs using the language's 
features; however, it does not discuss using the system to store the program in a file, get a 
printed listing of the program, or run the program. Such operations are described in the Getting 
Started Guide for Technical BASIC on your particular HP-UX system. If you have not yet read 
that manual, you should do so before getting very far into the details of this guide. 

If you have never programmed a computer before, you will probably be more comfortable starting 
with one of the many beginner's BASIC text books available from various publishing companies. 
However, some beginners may find that they are able to start in this guide by concentrating on 
the fundamentals presented in the first few chapters. 

If you are a programming expert or are already familiar with the BASIC language of other 
HP desktop computers, you may start faster by going directly to the HP-UX Technical BASIC 
Language Reference and checking the keywords you normally use. If you don't find the keywords 
you expect to find, then refer to the Table of Contents or Index for the appropriate topic. 

Once you have satisfied the above prerequisites, you are ready to being using Technical BASIC 
on the HP-UX operating system. 
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What's In This Guide? 

This section describes the contents of this guide. It discusses these topics: 

• What this guide contains 

• How it is organized 

• What it does not contain 

• How to read the guide 

• Previews of each chapter 

What this Guide Contains 

This guide provides programming techniques, helpful hints, and explanations of capabilities. 
It mainly consists of examples of BASIC algorithms used to perform programming tasks. Any 
BASIC statements appropriate to the topic being discussed are included in each chapter, whether 
they have been previously introduced or not. 

How It Is Organized 

The explanations and programming hints in this guide are organized topically. It reflects the 
organization of a well-written program: A program performs various "sub-tasks" as it completes 
its overall job, so many of these tasks can (and should) be viewed separately to be understood 
more easily and used more effectively. Here are two examples: 

• Perhaps you have reduced your favorite formula to program form and now want a graph of 
the results. You will find a chapter called "Graphics" that explains many ways to generate 
plots and graphs. 

• Perhaps you have experience in another programming language. You know exactly what 
a "loop" does, but you didn't find the statement you were looking for in the HP-UX 
Technical BASIC Language Reference. In the chapter on "Program Structure and Flow", 
there is a section called "Repetition" which explains the kinds of loops available and all 
the statements needed to create them. 
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What this Guide Does Not Contain 

This guide is not a rigorous description of the BASIC language; that is provided by the HP-UX 
Technical BASIC Language Reference. Because it is organized by topics and concepts, it is not 
a good place to find an individual keyword in a hurry. Keywords can be found using the index, 
but even so, they are often imbedded in discussions, contained in more than one place, or only 
partially explained. 

Also, this is not a good place to find complete syntactic details. Program statements are often 
presented only in the form that applies to the specific concept being discussed, even though there 
may be other forms of the statement that accomplish different purposes. If you want to quickly 
find the complete formal syntax of a keyword, use the language reference. It is specifically 
intended for that purpose. 

How to Read This Guide 

All readers should read this "Overview" chapter. Since you are now reading this discussion, 
you will have already learned much about the Technical BASIC documentation set. Whether or 
not you decide to read any of the other chapters of this manual, you will definitely benefit from 
reading the rest of this chapter. 

Once you have finished reading the subsequent "Chapter Previews" section, you should realize 
that many of the keys to designing Technical BASIC programs are revealed in the chapter called 
"Program Development." All readers should read that chapter also. 

Once you feel comfortable using the system, you may choose to read only the chapter(s) and 
section(s) that are relevant to your programming tasks. Since most users will not read this guide 
from cover to cover anyway, this approach should not present any significant problems. In those 
cases when you have difficulty getting the meaning of certain items from context, consult the 
Index to find additional information about that topic. 
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Use the Overviews 

We have attempted to provide many "overviews" and "previews" so that you can determine the 
contents of a chapter or section and then decide whether or not to read them. For instance, 
most introductions to chapters and sections provide a "bulleted list" of what the subsequent text 
describes. Here is an example: 

Bulleted lists provide the following features: 

• They "stand out" visually, allowing you to scan text and easily find them. 

• They provide a way of quickly delimiting several key points. 

• They allow you to maintain a "global" view, rather than getting bogged down in details. 

These lists will help you to more quickly learn the material provided in the text, as well as steer 
you around sections that are irrelevant to you at a particular time. 

Chapter Previews 

The following is a preview of each chapter in this guide. 

Chapter 1: Overview 

This chapter (the one you are now reading) covers the necessary prerequisites for using this 
guide and a description of each chapter. 

Chapter 2: Program Development 

This chapter discusses the overall process of developing programs. It briefly discusses the steps 
in designing, coding, debugging, and supporting programs. 

Chapter 3: Program Structure and Flow 

This chapter describes how you can tell a program to make decisions and then execute the 
corresponding part(s) of your program. 

Chapter 4: Numeric Computation 

This chapter covers mathematical operations and the use of numeric variables. It includes dis- 
cussions on types of variables, expression evaluation, arrays, and methods of managing memory. 
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Chapter 5: String Manipulation 

This chapter explains the programming tools available for processing strings. Strings are char- 
acters, words, and text. Since words are more pleasant than numbers to humans, skillful use 
of strings can make the input and output of programs much more natural to those using the 
programs. 

Chapter 6: User-Defined Functions and Subprograms 

This chapter discusses an outstanding feature of this language — its ability to call other program 
contexts and the speed with which it can do so. Alternate contexts, or environments, are available 
as user-defined functions or subprograms. 

Chapter 7: Error Handling 

This chapter discusses techniques for intercepting or trapping errors that might occur while a 
program is running. Many errors can be dealt with easily by a well written program. Error 
trapping keeps the program running and provides valuable assistance to the computer operator. 

Chapter 8: Program Debugging 

This chapter explains the powerful debugging features available on the Technical BASIC system. 
We all wish that every program would run perfectly the first time and every time. Unfortunately, 
there is little evidence in real life to support that dream. The next best thing is to get the 
computer to do most of the debugging work for you. 

Chapter 9: Communicating with the Operator 

This chapter provides suggestions and techniques for providing information to and receiving 
it from a person who is using the computer. For instance, it discusses techniques useful for 
creating organized, highly readable printouts on printers and display screens. 

Chapter 10: Using the Clock and Timers 

This chapter describes using the HP-UX system's real-time clock and the Technical BASIC 
system's timers. 

Chapter 11: Data Storage and Retrieval 

This chapter shows many of the alternatives available for storing the data that is intended as 
program input or created as program output. The two main means for storing and retrieving 
data are program files and mass storage data files. 
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Chapter 12: C Binaries 

This chapter explains how to make calls to programs written in the C languages from Technical 
BASIC programs. 

Chapter 13: Pascal Binaries 

This chapter explains how to make calls to programs written in the Pascal language from Technical 
BASIC programs. 

Chapter 14: FORTRAN Binaries 

This chapter explains how to make calls to programs written in the FORTRAN language from 
Technical BASIC programs. 

Chapter 15: Graphies 

This chapter discusses the techniques of programming with graphics and how they are very 
useful for displaying data in a form that humans easily understand. 
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There are several stages in the design and development of programs: determining what is re- 
quired; outlining algorithms and data structures; translating the algorithms and data structures 
into BASIC statements (coding); checking to see that the program works without errors (debug- 
ging); documenting the program; and supporting and enhancing it. 

There are also several steps in the mechanics of program development once you begin coding 
the program: entering, storing, listing, and editing it. 

Chapter Contents 

This chapter contains the following areas of program development: 
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Mechanics of Program Development 
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2-24 
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General Steps in Program Development 

This section describes the general steps that you will take as you develop programs. The 
following sections in this chapter and manual show how to apply them. 

1 . Understand and describe the problem. You cannot design a solution to a problem without 
clear understanding of the problem. You must get a clear grasp of these two elements: 

a. What action the program is required to perform. 

b. What data it will be given or will compute. 

1. Even though this step sometimes seems trivial or obvious, taking time to methodically 
describe it may simplify the design process immensely. 

2. Outline the solution. This phase initially consists of verbally describing what steps your 
program will take to solve the problem. At this point, splitting up the program's respon- 
sibilities into various tasks is very important, especially if each task is to be written by a 
different programmer. Interactions between various tasks are also important. 

3. Design algorithms and data structures, and then refine. The algorithms that you design 
(or choose from computing literature) will consist of the individual steps that your program 
will take. The data structures required may be global or applicable to only one or two 
steps of the overall solution. 

The "refine" part of this step suggests the highly effective approach of beginning with 
large tasks and then breaking each one up into smaller tasks. You can keep repeating this 
approach on each subtask, until you have broken the problem up into a set of rudimentary 
steps. 

4. Code the data structure and algorithms. This step involves translating the data structure 
and algorithms defined in earlier steps into the programming language that you will be using 
— in this case, BASIC. This guide gives several examples of programs and code segments 
which are implementations of various algorithms. 

5. Debug and test the program. Debugging a program involves getting the program to 
run without crashing and giving you BASIC error messages like Error 56: STRING OVF. 
Testing a program involves making sure that it does what you want it to do. Ideally, you 
should be able to test each separate "module" of your program independently, which is 
sometimes called "bottom-up" testing. The chapter called "Debugging Programs" discusses 
these topics in greater detail. 

6. Document and support it. Documenting the program involves telling both the program's 
users and its future supporters what the program does. See the section of this chapter 
called "Documenting Your Programs" for further details. Support involves fixing bugs and 
enhancing the program. 
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Sample Development Session 

The remaining sections of this chapter, and some subsequent chapters, show how to apply the 
suggestions in the preceding section in developing a simple "budget" program. Seeing that the 
suggestions really work will help you to have faith in them and begin to apply them. 



Step 1 : Understand and Describe the Problem 

As you begin to conceptualize your budget program, one of the first question you might ask is, 
"What is a budget for?" The answer is that it is an attempt to evaluate present income and 
spending for the purpose of planning and controlling future income and spending. But how does 
it help you accomplish these two tasks? Here some things that will help you to evaluate present 
income and expenses. 

1. Determine target income and expenses. 

2. Determine actual income and expenses. 

3. Calculate the differences between the targets and actuals. 

For simplicity, using this information in planning and controlling future income and spending will 
not be part of the program's responsibility. 
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Now that the program's action has been generally defined, you are ready to ask the second 
question: "What data is required?" Here is an example of the data that the user will supply 
to the program (also known as input data): 



Income 



Category 



Target 



Actual 



Payroll 
Investments 



1680.56 
345.67 



1680.56 
290.32 



Expenses 



Category 


Target 
654 . 32 


Actual 


Mortgage 


654 . 32 


Taxes 


432.10 


432.10 


Insurance 


123.45 


123.45 


Food 


432.00 


501.81 


Medical 


75.00 


125.90 


Transportation 


165.00 


134.32 


Education 


100.00 


95.00 


Entertainment 


75.00 


98.55 



Alphanumeric data will be used in the "Category" column; with BASIC, this data type is also 
known as string data. The data in the "Target" and "Actual" columns will be real numbers. 
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Here is an example of the data that the program will compute and display for the user (also 
known as output): 



Income 



Category- 



Payroll 

Investments 

Total difference - 55.35 



Diff 
$ 


erence 

7. 


0.00 





- 55.35 


- 16 



Expenses 


Category- 


Diff* 
$ 

0.00 


srence 




Mortgage 







Taxes 


0.00 







Insurance 


0.00 







Food 


+ 69.81 


+ 16 




Medical 


+ 50.90 


+ 68 




Transportation 


- 30.68 


- 19 




Education 


- 5.00 


- 5 




Entertainment 


+ 23.55 


+ 31 




Total difference 


+ 108.58 




Net Savings 


Deposit 
(Withdrawal) 


( 163.93 ) 





The "$ differences" will be represented as real numbers, since it may be important to keep track 
of cents as well as dollars. The "% differences" can be integers, since 1% resolution is probably 
adequate. 

Now that you understand and can describe the problem, both in terms of what it does and what 
data is required, you are ready to begin creating the solution. 
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Step 2: Outline the Solution 

Here are the general steps that a program can take to solve the problem: 

1. Show you the target income and expenses (for all categories). 

2. Ask you for the actual income and expenses (for each category). 

3. Compute the differences between target and actual (for each category). 

4. Show you the results (for all categories). 

5. Compute the difference between total income and total expenses. 

6. Show you the net deposit to (or withdrawal from) your savings. 

Maintain Proper Perspective 

At this point, you should not get into the details of any step; just stick to the broad perspective. 
You will be getting into more details in the next step. By hiding the details of each step in a 
procedure, you can more easily understand what is happening in the procedure (and consequently 
maintain better control of it). 

Let the Data Structure the Algorithms 

You can now begin to see that the steps are more or less structured according to the data that 
you have. This is in fact one of the most important principles that you can use in designing your 
programs: Let the structure of the data determine the structure of the algorithms. 



2-6 Program Development 



Step 3: Design, and Then Refine 

You have shown what general steps the program will take to solve the problem, but you have 
not yet described the procedure explicitly enough for a computer to understand what you want 
it to do (at least not for the Technical BASIC language). The next step is to take each of these 
general steps and begin to refine it, or break it down into smaller and smaller tasks. 

For brevity, let's take the first step: 

1. Show you the target income and expenses (for all categories), and break it down into 
smaller steps. 

a. For each income category: 

• Determine the target income value. 

• Display the category name and target value. 

b. For each expense category: 

• Determine the target expense value. 

• Display the category name and target value. 

With this level of detail you can begin translating the algorithm into BASIC code. 
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Step 4: Code the Program 

This section consists of two parts: 

• The first part gives a brief description of the fundamental building blocks of a BASIC 
program. 

• The second part, called "Back to Step 4," presents a BASIC program. 

If you already know another version of BASIC, or other programming language, then you may 
want to skim the first section, called "Elements of a BASIC Program." 

Elements of a BASIC Program 

This section describes the fundamental building blocks of Technical BASIC programs. These 
terms and concepts will prepare you for translating your data structure and algorithms into 
BASIC code. 

Keywords 

A keyword is a group of characters that is understood by the BASIC language system to invoke 
some predefined action. Examples of keywords are BEEP, DISP, INPUT, and LET. 

Statements 

A statement is a keyword (sometimes optional) followed by any parameters, lists, specifiers, and 
secondary keywords that are allowed with that keyword. These are examples of statements: 

BEEP Tells the computer to produce a short beep. 

DISP "THIS IS A STATEMENT" Tells the computer to display the message "THIS IS A 

STATEMENT" on the screen. 

INPUT Income Tells the computer to allow the user to enter a value (from 

the keyboard) into the numeric variable named Income. 

LET Expense=iO Tells the computer to assign a value of 10 to the numeric 

variable named Expense. 



NOTE 

Note that the notation used in this guide is to print the statements that 
you can actually type into the computer in a special dot-matrix font. 
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Program Lines 

A program line contains a line number followed by at least one BASIC statement. Here are two 
legal program lines. 

10 PRINT "THIS IS A PROGRAM LINE" 
20 END ! SO IS THIS 

Line 10 prints the characters between the quotes, while line 20 indicates the end of the program. 
The text following the END statement on line 20 is a comment; it is separated from the END 
statement with the exclamation point. 

You can place several statements on a single program line by separating them with @ character. 
10 PRINT "THIS IS A " 3 PRINT "PROGRAM LINE" 

A line number may be optionally followed by a line label. A line label is a name that is placed 
after the line number and is terminated by a colon (:). 

20 Done: END ! SO IS THIS 

The subsequent section called "Documenting Your Programs" further describes using comments 
and line labels. 

Programs 

In Technical BASIC, a program is a list of program lines, usually with an END statement on the 
last line. The two following program lines define a program. 

10 DISP "THIS IS A PROGRAM LINE" 
20 END ! SO IS THIS 

The maximum length of a program line entered from the keyboard is 159 characters 1 unless you 
have a line-oriented terminal where the maximum length is 80 characters per line. Check the 
"GLOSSARY" of the HP-UX Technical BASIC Language Reference under line-oriented terminal. 



BASIC program lines longer than 159 characters can be created using another editor and then retrieved with the GET statement; however, 
only the first 159 characters will be stored on the line. 
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Data Types 

With Technical BASIC, there are two general pre-defined types of data: numeric and alphanu- 
meric (or "string"). And within the numeric data category, there are two divisions: real 1 numbers 
and integers. Here are examples of each. 



String 


Real 


Integer 


Short 


a 

Word 

MORE letters 


1.2 
1E+300 


16 
32 767 


—1.987 
1E+10 



Here are examples of creating storage locations, called variables, for these fundamental types of 
data. 



DIM StringVar$ [20] 



Declares a simple variable named StringVar$ to be of type string, 
and allocates a storage space of size 20 characters for it. 



INTEGER WholeNumber 



Declares a simple variable named WholeNumber to be of type IN- 
TEGER, and allocates the corresponding amount of memory for it. 



SHORT ShortReal 



Declares a simple variable named ShortReal to be of type SHORT, 
and allocates the corresponding amount of memory for it. Note that 
real variables of type SHORT are stored in half the memory that it 
takes for a variable of type REAL. 



REAL LongReal 



Declares a simple variable named LongReal to be of type REAL, and 
allocates the corresponding amount of memory for it. 



REAL RealArray(lO) 



Declares an array variable named Real Array to be of type REAL, 
and allocates the corresponding amount of memory for it. The 
array structure in BASIC is a group of variables, each of which 
has the same data type and variable name. Each variable in the 
array is specified by an index value; for instance, the 4th element 
is RealArray(4), if OPTION BASE 1 is in effect. Note that OPTION 
BASE determines the lower bound(s) of a numeric or string array's 
subscript(s); the default is OPTION BASE . 



You can also use these fundamental types to implement your own data types, if you wish. 



With HP-UX Technical BASIC, there are actually two predefined representations of real numbers: REAL and SHORT. The difference 
between the two is the range of values that they can represent. See the chapter called "Numeric Computation" for further details. 
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Functions 

Functions perform operations that always return a value. The Technical BASIC system provides 
two types of functions: 

• Resident — provided by the system. 

• User-defined — you can implement these yourself. 

Resident functions are part of the BASIC language. For instance, SIN (PI/2) and CHR$(10) are 
examples of calling the resident functions SIN and CHR$, respectively. Resident functions are 
discussed in the "Numeric Computations" and "String Manipulations" chapters. 

You can implement your own user-defined functions to provide any function you desire. These 
types of functions are described in the "User-Defined Functions and Subprograms" chapter. 

Subprograms 

Subprograms also perform operations, but they do not necessarily return a value. Like programs, 
subprograms are also lists of program lines, but they can be stored independently and "called" 
from a main program or another subprogram. Each is also stored in its own portion of BASIC 
memory, which is separate from the main program. Here is a simple example subprogram: 

100 SUB "FirstSub" 

110 DISP "This is displayed by 'FirstSub'." 

120 SUBEND 

Here is how you can call it from a main program. 
100 CALL "FirstSub" 

Subprograms are a useful programming tool, but the computer is capable of running just fine 
without them. Subprograms are covered in depth in the chapter called "User-Defined Functions 
and Subprograms". 

Binary Programs 

The Technical BASIC system has the capability of loading and calling "binary programs". The 
term "binary programs" is used to identify programs that are stored in the "machine" language 
used by the computer's central processor, rather than in a high-level language like BASIC. Thus, 
"binary" programs can be run directly by the processor, rather than having to be translated from 
the high-level language into machine language. 

The usual purpose of a binary program is to add capabilities to the language of the computer. 
In this respect, the computer's operating system and the Technical BASIC system might be 
considered "binary programs". However, they cannot be accessed using the CALLBIN statement. 
For further details read the "Binary Programs" chapter. 
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Commands (Not Part of Programs) 

Commands are like statements in that they consist of a keyword, and sometimes appropriate 
parameters; however, they cannot be stored in a program line — you can only execute them 
from the keyboard. Examples of commands are DELETE and SCRATCH. 

Back to Step 4 

Now that you have seen the building blocks of a program, you are ready to begin translating it 
into BASIC language code. For convenience, here are copies of the data structure and algorithm 
from the solution presented earlier. The translation into BASIC code follows: 



Data structure 




Income 




Category 


Target 


Payroll 


1680.56 


Investments 


345 . 67 



Algorithm 

For each income category: 

• Determine the target income value. 

• Display the category name and target value. 

A Coded Program Segment 

Here is one way of implementing the data structure and algorithm. (Don't be concerned if you 
don't understand every line of the program right now; each line is explained after the program 
listing.) 

100 ! Allocate memory for data storage . 

110 OPTION BASE 1 

120 DIM IncomeName$(2) 

130 REAL TargetIncome(2) 

140 ! 

150 ! Assign values to variables. 

160 LET IncomeName$(l)="Payroll" 

170 LET IncomeName$(2)="Investments" 

180 LET Targetlncome(l)=1680.00 

190 LET TargetIncome(2)=345.67 

200 ! 

210 DISP " Category Target" 

220 DISP " " 

230 DISP IncomeName$(l) .Target Income (1) 

240 DISP IncomeNameS (2) .Target Income (2) 
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Here are the results of running the program: 
Category Target 



Payroll 1680 

Investments 345 . 67 

Here is a line-by-line description of what the program does. You can skip the explanation if you 
already understand what is happening. 

Line 100 is a comment. It is a way for the programmer to describe what he is doing in the 
program; they help him to understand what the program is doing the next time that he edits it. 
It is especially useful when he, or someone else, must modify the program a long time later. 

Line 110 defines the lower bound of array element indexes. In this case, a value of 1 dictates 
that the first element of an array is specified with an index value of 1; e.g., IncomeName$(l). 
OPTION BASE indicates that the first element would be specified with an index value of 0; e.g., 
IncomeName$(0). 

The DIM statement on line 120 declares the string variable named IncomeName$, and allocates 
memory for it. In this case, the subscript (2) specifies that it is an array variable with 2 elements 
(1st, and 2nd) which are both string variables. 

The REAL statement on line 130 performs the same function for the real array called Actualln- 
come. 

Lines 140 and 150 are also comments. 

The LET statement on line 160 stores the characters "Payroll" in element 1 of the string array 
variable named IncomeName$. Line 180 performs a similar function for element 1 of the REAL 
array named Targetlncome. Lines 170 and 190 perform similar operations for element 2 of the 
respective arrays. 

Line 200 is another comment. 

The DISP statements on lines 210 through 240 display messages on the CRT screen. The first 
two DISP statements display the table headings, while the second two display values in the table. 
On line 230 the index value of 1 specifies that 1st element of the IncomeName$ string array is 
to be displayed. This string variable's value is "Payroll". Similarly, the value of the 1st element 
of the Targetlncome array is 1680. 
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Mechanics of Program Development 

Now that you have a real program to work with, the next step is to learn the mechanics of 
entering, storing, listing, and running programs. Some of these operations are system-dependent; 
in other words, they vary slightly according to the HP-UX system you are using. Therefore, 
they have been covered in the Getting Started Guide for your particular HP-UX Technical BASIC 
system. 

Here is the list of operations covered therein: 

• Initial program entry using the Technical BASIC editor, including specifics of using your 
keyboard. 

• Storing the program in a file (STORE or SAVE). 

• Checking to see if the file was stored (CAT). 

• Getting a listing of the program (LIST and PLIST). 

• Running the program (RUN). 

• Getting a hardcopy of the screen (DUMP ALPHA and DUMP GRAPHICS). 

• Dealing with error messages. 

If you are not familiar with these operations, please refer to your Getting Started Guide now. 

Global Program Editing 

The Getting Started Guide for your particular Technical BASIC system describes entering pro- 
grams using the BASIC editor; it also describes editing programs on a line-by-line basis. This 
section describes the following "global" program editing operations which are provided by Tech- 
nical BASIC keywords: 

• Inserting new program lines between existing lines. 

• Deleting existing lines. 

• Renumbering existing lines. 

• Scanning for string literals. 

• Renaming variables. 

• Copying and moving program segments. 
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Inserting Lines 

Lines can be easily inserted into a program. As an example, assume that you want to insert 
some lines between line 200 and line 210 of our example program. 



180 LET Targetlncome(l)=1680.00 

190 LET Target Income (2) =345. 67 

200 ! 

210 DISP " Category Target" 

220 DISP " ' 



You can begin by numbering the first line 201, the second one 202, and so forth (up through 
209 without overwriting existing lines). 

201 CLEAR ! Clear the alpha screen. 

202 ! 

Note that while inserting lines, you should keep track of the line numbers you have inserted so 
that you do not inadvertantly: 

• Overwrite existing lines. 

• Insert lines into the wrong place. 

You can generate a program listing with LIST or PLIST to keep track of where lines have been 
placed. 



180 LET Targetlncome(l)=1680.00 

190 LET TargetIncome(2)=345.67 

200 ! 

201 CLEAR ! Clear the alpha screen. 

202 ! 

210 DISP " Category Target" 

220 DISP " ' 
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Deleting Lines 

The DELETE command can be used to delete single or groups of program lines. When the 
keyword DELETE is followed by a single line number, only a single line is deleted. For example, 
executing: 

DELETE 201 

deletes only line 201 of your program. 

Blocks of program lines can be deleted by using two line numbers in the DELETE command. The 
first number identifies the start of the segment to be deleted, and the second number identifies 
the end of the segment to be deleted. Here are some examples. 

DELETE 100,200 deletes lines 100 thru 200, inclusively. 

DELETE 150,65535 deletes all the lines from line 150 through the end of the program. 

DELETE 100 , 10 would do nothing except generate an error if a program is currently in 

memory. 

Renumbering a Program 

No matter how careful you have been while entering lines, there will inevitably be a time when 
you need to renumber a program. And it is also good practice to renumber occasionally to 
improve readability. 

You can renumber a program by using the REN command. When no parameters are specified, 
the first line number is renumbered to 10 and the line-number increment is 10. 
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Both the starting line number and the interval between lines can be specified. For example, 
this command renumbers the entire program, using 100 for the first line number and an increment 
of 5. 

REN 100,5 

100 ! Allocate memory for data storage. 

105 OPTION BASE 1 

110 DIM IncomeName$(2) 

115 REAL TargetIncome(2) 

120 ! 

125 ! Assign values to variables. 

130 LET IncomeName$(l)="Payroll" 

135 LET IncomeName$ (2)=" Investments" 

140 LET Targetlncome(l)=1680.00 

145 LET Target Income (2) =345. 67 

150 ! 

155 CLEAR ! Clear alpha display. 

160 ! 

165 DISP " Category Target" 

170 DISP " " 

175 DISP IncomeName$(l) .Target Income (1) 

180 DISP IncomeName$(2) ,TargetIncome(2) 

If only the beginning line number is specified, a line-number increment 10 is assumed. For 
example, this command renumbers the entire program using 1000 for the first line number and 
an increment of 10: 

REN 1000 

1000 ! Allocate memory for data storage. 

1010 OPTION BASE 1 

1020 DIM IncomeName$(2) 

1030 REAL TargetIncome(2) 

1040 ! 

1050 ! Assign values to variables. 

1060 LET IncomeName$(l)="Payroll" 

1070 LET IncomeName$ (2)= "Investments" 

1080 LET Targetlncome(l)=1680.00 

1090 LET TargetIncome(2)=345.67 

1100 ! 

1110 CLEAR ! Clear alpha display. 

1120 ! 

1130 DISP " Category Target" 

1140 DISP " " 

1150 DISP IncomeName$(l) .Targetlncome(l) 

1160 DISP IncomeName$(2) ,TargetIncome(2) 
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You can also renumber a portion of a program. For instance, this command renumbers only 
line numbers 1000 through 1080 to lines 10 through 90. 

REN 10,10,1000,1080 

10 ! Allocate memory for data storage. 

20 OPTION BASE 1 

30 DIM IncomeName$(2) 

40 REAL Target Income (2) 

50 ! 

60 ! Assign values to variables . 

70 LET IncomeName$(l)="Payroll" 

80 LET IncomeName$(2)="Investments" 

90 LET Targetlncome(l)=1680.00 

1090 LET TargetIncome(2)=345.67 

1100 ! 

1110 CLEAR ! Clear alpha display. 

1120 ! 

1130 DISP " Category Target" 

1140 DISP " " 

1150 DISP IncomeName$(l) .Target Income (1) 
1160 DISP IncomeName$ (2) .Target Income (2) 



NOTE 

Note that the REN command cannot be used to move lines. Moving and 
copying program lines is the topic of a subsequent section. 



To get back to the original program, you can use this sequence: 

DELETE 1110.1120 
REN 100 

Scanning for Literals 

The SCAN command is used for finding all the occurrences of a particular string literal or variable 
name in a program. In our continuing example program, let's look for the literal "Income": 

SCAN "Income" 
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Here is the system's response: 

Scanning . . . 

130 REAL Target Income (2) 

180 LET Targetlncome(l)=1680.00 

190 LET TargetIncome(2)=345.67 

210 DISP " Category Target" 

230 DISP IncomeName$(l) .Targetlncome(l) 

240 DISP IncomeName$(2) ,TargetIncome(2) 

. . . end of scan 

Here is a more useful example. Suppose that you have the string literal "Tax" in several places 
in your program, and you want to change it to either "State Tax" or "Federal Tax" — and which 
one you change it to depends on the context of the statement. Use the following command to 
find and list all occurrences of the string "Tax": 

SCAN "Tax" 

You can then look at each line and decide whether it should be changed to "State Tax" or 
"Federal Tax". 

To verify that all change(s) have been made, execute another SCAN command specifying the 
string for which you were originally searching. (Using this command avoids a long listing of the 
program.) The command lists all program lines containing the string "State Tax" or "Federal 
Tax", since the string "Tax" is a subset of those strings. 

Renaming Variables 

You can rename variables with the the REPLACEVAR. . .BY command. Here is an example: 

REPLACEVAR Targetlncome BY TargetExpense 

REPLACEVAR. . .BY is like SCAN in that it looks for specific patterns of characters; however, RE- 
PLACEVAR is different in two ways: 

• It can only find occurrences of the specified variable name, not any combination of char- 
acters in the program. 

• It automatically replaces the first variable name with the second one. 

Here is an example of replacing one variable name with another. Suppose that you have the 
following program in memory: 

10 A=20 
20 B=30 
30 T=A+B 
40 DISP T 
50 T=A*B 
60 DISP T 
70 END 
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You decide after entering the program that you want to replace the variable "T" with the 
variable name "RESULT" , but you do not want to go through the program and replace "T" 
with "RESULT" everywhere you see it as it would take a long time to do so. This is particularly 
true for large programs. The following command allows you to do this: 

REPLACEVAR T BY RESULT 

When you do a listing of you program it now looks like this: 

10 A=20 

20 B=30 

30 RESULT=A+B 

40 DISP RESULT 

50 RESULT=A*B 

60 DISP RESULT 

70 END 

Copying and Moving Program Segments 

During program development you often enter a section of code that performs some function, 
thinking that this function will be needed at that place. Sure enough, a short time later you find 
that you need to move it to another location. But how on earth do you move those thirty-five 
lines of code? You certainly do not want to retype the whole thing. 

The following paragraphs show you how to move program segments using three different meth- 
ods: 

• Using the Technical BASIC editor (if you have a terminal or console that supports screen- 
oriented editing). 

• Using Technical BASIC'S STORE and MERGE commands. 

• Using the HP-UX system's "vi" editor 

Moving Lines with the Technical BASIC Editor 

NOTE 

You can only use this method if you have a terminal or console that 
supports screen-oriented editing. See the Getting Started Guide for your 
particular Technical BASIC system to determine whether your terminal 
or console supports this feature. 



2-20 Program Development 



Here are the steps that you will be taking with this method: 

1. Perform a LIST operation on the lines to be moved. 

2. Change a statement's line number by moving the cursor onto the line and typing over the 
existing number. 

3. Store the line by pressing the carriage return key. 

4. Repeat steps 2 and 3 until you have changed the line numbers of all program lines to be 
moved. (You may have to perform another LIST if you are moving more than a screenful 
of lines.) 

5. Verify that the lines have been copied into the desired location. (Note that the original 
lines are still present.) 

6. DELETE the original copies of the lines. (If you are duplicating the lines into another 
location, then you will skip this step.) 

Moving Lines with the MERGE Command 

The following procedure allows you to move a program segment using the Technical BASIC'S 
MERGE command. 

1. Store the program which you have just entered under a file name of your choosing by 
executing a STORE command that specifies the desired file name. 

2. To assist in determining where the lines are you wish to move, list the program using the 
LIST statement. Make a note of those lines for later reference. 

3. Delete all the lines in your program except those which you wish to move to another 
location in the program. Use the DELETE command, which was explained earlier in this 
section. 

If, for instance, you want to move lines 300 through 390 to another location, you could 
execute: 

DELETE 1,299 

and then execute 

DELETE 391. lastjine 

4. Store the remaining lines in a temporary file. Use the STORE command and specify the 
name of the temporary file; this file's name must be different from the one you stored in 
step 1. 

5. Reload the original program. 



Program Development 2-21 



6. Delete the lines in this file that you want to move. (If you are just making a second copy 
of these lines, you can skip this step.) 

If, as in the preceding example, you were moving lines 300 through 390, you would now 
delete these lines: 

DELETE 300,390. ( 

7. Finally, merge the lines stored in the "temporary" file into the new location in original 
program. 

Use the MERGE command and specify the temporary file's name. Following the file name, 
specify the line number where you want the insertion to occur and the increment for 
each line. Note that the increment of 1 is used so that lines of the existing program 
are not overwritten and that lines are not "interleaved" between existing lines of code. 
For example, if you were merging the contents of the file named TEMP into this program, 
beginning at line 850, you would specify that line number and the increment of 1 after the 
file name. Your statement would be specified as follows: 

MERGE "TEMP" 850,1 
After executing the above procedure, purge the temporary file by using PURGE. 

Moving Lines with the HP-UX vi Editor 

The editors available on your HP-UX system read and write text using ASCII-format files. The ( 
Technical BASIC system can also read and write ASCII files using the GET and SAVE commands. 
The general procedure you will use is as follows: 

1. Create a program with the BASIC editor, SAVE it in an ASCII file, and exit the BASIC 
system. 

2. Read this file with an HP-UX editor, and move the desired lines. Note that your program 
lines and statements refering to them have to be renumbered. Then store this modified 
file, and exit the HP-UX editor. 

3. Load the modified file into BASIC memory with the GET command. 
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Here are the details of the preceding procedure using the HP-UX system's ui editor. 

1. While in BASIC, use the SAVE command to store the program. This command creates an 
ASCII file and stores the program as ASCII text in the file. 

2. Exit the BASIC system. 

3. Execute the ui command, specifying the name of the file saved in step 1. 

4. Locate the program lines you want to move and place the cursor on the first line to 
be moved. Next, type the number of program lines you wish to move followed by the 
uppercase letter Y (for "yank"). This will place the indicated number of program lines into 
the ui editor's buffer. 

5. Next, move the cursor to the line above which you wish to copy the text contained in the 
buffer. Type an uppercase P (for "put"). Your program lines have been moved; however, 
the same program lines still exist in their previous location and need to be removed from 
the program. To remove these line place the cursor on each of the lines to be removed 
and type lowercase dd. 

6. Renumber the program lines and statements refering to them. 

7. Store the file by typing uppercase ZZ. Typing this command also exits the ui editor. 

8. Enter the BASIC system. Execute a GET command, specifying the name of the modified 
file. 
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Step 5: Debug and Test 

This phase of the development process involves two main things: 

• Getting the program to run (without program-execution errors). 

• Making sure the program does what is expected. 

Since these are rather large topics, they are discussed in the separate chapter called "Debugging". 
Both debugging and testing programs are mentioned there, but the focus is on the Technical 
BASIC features available for debugging. An exhaustive treatise of software testing is beyond the 
scope of this manual. 



Step 6: Document and Support 

Documentation for a program describes relevant facts about the program, such as what the 
program does and what kind of data it requires. Support involves both fixing errors and adding 
enhancements. Documentation is described in this chapter, but a detailed treatment of software 
support is beyond the scope of this text. 

There are basically two types of documentation that you can produce for your programs: 

• Internal documents — those available to someone supporting or enhancing the program. 

• External documents — those available to the program's users. 

Internal Documents 

There are basically two ways to document programs for those who will be supporting or revising 
them: 

• Within the program itself. 

• In a separate document. 

The focus of this section is on self-documenting programs. The topic of producing separate 
documents, while extremely useful, is not discussed in this manual. 
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Internally Self-Documenting Programs 

When first learning how to program, many people may view the use of comments, long variable 
names, descriptive printouts, and other documentation tools as merely extra typing that is not 
really necessary in their short programs. However, as old programs are expanded or become 
more widely used, or new programs are written, software support activities eventually become 
necessary. For example, when some obscure bug is found, someone must address the problem. 

A programmer (often the original designer) picks up a copy of the program written a year ago 
and can't begin to see what "XI" was or why you would ever want to divide it by "X2". Program 
documentation can make the difference between a supportable tool that adapts to the needs of 
the users and a support nightmare that never really does exactly what the current user wants. 
Keep in mind that the local software support person just might be you. 

Relevant Features 

The Technical BASIC language on HP-UX makes it easy to write self-documenting programs. In 
addition to BASIC'S standard REM (remark) capability, its primary documentation features are as 
follows: 

• Line labels (up to 32 characters) 

• Variable names (up to 32 characters) 

• Remark (REM) statements 

• End-of-line comments (that follow statements on a program line) 

• Indentation of statements on program lines 

Although this section deals primarily with commenting methods, all of these features work 
together to make a readable program. 

A Comparison 

The following example shows two versions of the same program. 

• The first version is uncommented and uses "traditional" BASIC variable names. 

• The second version uses the features of the Technical BASIC language to make the program 
more easily understood. 

After reading both programs, answer this question: Which version would you rather work 
with? 
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100 A=0 . 03 

110 B=0.02 

120 C=A+B 

130 D=0 

140 DISP "Input item price" @ INPUT D 

150 IF D<0 THEN GOTO 210 

160 E=D*C 

170 F=D+E 

180 DISP "Tax =";E,"Item cost =" ;F 

190 DISP 

200 GOTO 130 

210 END 



100 

110 

120 

130 

140 

150 

160 

170 

180 

190 

200 

210 

220 

230 

240 

250 

260 

270 State_tax=.03 ! 

280 City_tax=.02 

290 ! 

300 Tax_rate=State_tax+City_tax 

310 ! 

320 Get_price: ! Start of main loop 

330 Price=0 ! Don't change totals if no entry 

340 DISP "Input item price (negative price to quit)." 

350 INPUT Price 

360 IF Price < THEN GOTO Finished 

370 Tax=Price*Tax_rate 

380 Item_cost=Price+Tax 

390 DISP "Tax =";Tax," Item cost =";Item_cost 

400 DISP 

410 GOTO Get_price ! Repeat loop for next item 

420 ! 

430 Finished: END 



This program computes the sales tax 
for a list of prices. 

Input: Item prices are input individually. 

Output : The tax and total cost for 
each item are displayed. 

Program terminated with negative cost . 

Sales tax rates are assigned on lines 270 
and 280. The rates used in this version 
of the program were in effect 9/1/84. 

Local tax rates 
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There are two methods for including comments in your programs. The use of an exclama- 
tion point is demonstrated in the second example program. The exclamation point marks the 
boundary between an executable statement and comment text. There does not have to be an 
executable statement on a line containing a comment. Therefore, the exclamation point can be 
used to introduce a line of comments, to add comments to a statement, or simply to create a 
"blank" line to separate program segments. Exclamation points may be indented as necessary 
to help keep the comments neat. 

Note that when the exclamation point is used on the same line as syntax, the exclamation point 
and comment are moved a space away from the syntax by the interpreter. If you wish to make 
your comment stand out from the syntax on that line, you need to use blank spaces between the 
exclamation point and the comment. An example of this was shown in the previous program. 

The REM statement can also be used for comments. The exclamation point is neater and more 
flexible, but the REM statement provides compatability with other BASIC languages. The REM 
keyword must be the first entry after the line identifier and must be followed by at least one 
blank. Here are some examples of comments. 

Obscure Better 

20 REM bal. array 20 REM Check Book Balance 

50 X=PI*R~2 50 X=PIR~2 REM Area of circle 

General Suggestions on Comments 

Each programmer has an individual style in the use of comments. Therefore, the following are 
not formal rules — they are simply some general suggestions on the effective use of comments. 

• Include a heading on programs that tells the purpose of the program: Why was the program 
written? What does it do? Who will probably be using it? 

• Give any helpful support information, such as the author of the program, the revision date, 
where to call or write for help, and instructions for any modifications that might be made 
by a normal user. 

• Identify all significant variables, especially global variables. A descriptive variable name 
may do the job, or a more detailed explanation may be needed. 

• Describe any input or output devices that are required for the proper running of the 
program. This may even include an explanation of how to modify the program to accom- 
modate alternate devices (when such changes are reasonable). 
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• Make major segments and entry points visible. Many tools are available for this, including 
descriptive line labels, indenting (described in the next section), spacing, and comments 
describing program flow. 

• Use comments freely to describe the action of complex lines, equations, fancy manip- 
ulations, and "low-level" operations like escape code sequences. These heavily coded 
operations can be very important to the computer and very mysterious to the human 
trying to read the program. 



Indenting 

Indenting is used to make the structure of a program more intuitively obvious by placing program 
lines in their "appropriate places". "Appropriate places" means indenting whenever there is a 
beginning or end of a program statement which: 

• causes looping, 

• is conditionally executed, 

• is a separated program segment (such as a function), 



is the first character of each program line contained in that segment 
number. 



excluding the line 



The following program is an example of indenting and commenting (but a poor example of 
variable names): 

Prints heading. 
Begins "I" loop. 
Begins "J" loop. 

Ends "J" loop. 
Ends "I" loop. 



10 


PRINT " 


I 


J" 


i 1 




20 


FOR I = 


1 


TO 


3 ! 




30 


FOR . 


J = 


= 4 


TO 


6 


40 


PRINT I; J 




50 


NEXT 


J 


! 






60 


NEXT I 


! 








70 


END 
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External Documentation 

Like internal program documents, there are two ways that external documentation can be pre- 
sented to the user: 

• By the program itself. 

• In a separate manual. 

Externally Self-Documenting Programs 

Ultimately, a program should require no external documents for its users. It should communicate 
what it does and how to use it through these two principles: 

• If it operates "as the user would expect," then it doesn't need any documentation. The 
chapter called "Communicating with the Operator" presents some examples of this princi- 
ple. 

• If an interaction is so complex as to require description, then it should do so while it is 
running. For instance, it should prompt the user for data when required, giving as much 
description as necessary. , 

Since most programs do not have this level of "human interface," you will probably need to 
produce an external document for the human who is to use it. 

External User Documents 

Although the topic of producing documentation for the program user is a large one, here are a 
few general suggestions: 

• Give users a global view of all the things that they can do with the program. 

• Describe how to complete each task. Present these discussions in logical progression. 

• Provide relevant examples, and be sure that they work. 

• If a task requires some level of expertise or knowledge, then state what is required. If 
possible, present relevant concept(s) at that point. If that is not possible, then give them 
a way to fulfill the requirement (such as by consulting another document or local expert). 

• Summarize tasks at the end of tutorials. 
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Notes 
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Program Structure and Flow 



3 



Two of the most significant characteristics of a computer lie in its abilities to: 

• Perform quick and accurate computations. 

• Execute decisions within programs. 

If the execution sequence could never be changed within a program, the computer could do little 
more than plug numbers into a formula. Technical BASIC has powerful computational features, 
but the heart of its usefulness is its ability to make decisions. 

The computational power of Technical BASIC is exercised as it evaluates the expressions con- 
tained in the program lines. The chapters entitled "Numeric Computation" and "String Manipu- 
lation" present the various tools available for data manipulation. 

The decision-making power is used to determine the order in which lines will be executed. This 
chapter discusses the ways of controlling the "flow" of program execution. 



Chapter Contents 

Here are the general topics covered in this chapter. 



Tasks/ Topics 


Page 


The program counter 


3-2 


Sequences of program flow 


3-3 


Linear flow 


3-3 


Halting program execution 


3-3 


Simple branching 


3-6 


Selection of program segments 


3-10 


Repetition of program segments (looping) 


3-17 


Event-initiated branching 


3-24 


Chaining programs 


3-30 


A closer look at program execution 


3-32 
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The Program Counter 



The key to the concept of decision making in a computer is an understanding of the program 
counter. The program counter is the part of the computer's internal system that tells it which 
line to execute. Unless otherwise specified, the program counter automatically updates at the 
end of each line so that it points to the next program line. This is illustrated in the following 
drawing. 



Program Lines 

120 R=R+2 

130 A r e a = P I * R - 2 

131 PRINT R 

140 PRINT "Area 
150 STOP 



Value in Program Counter 
at End of Line 



5 A re a 



This fundamental type of program flow is called "linear flow". As shown by the arrow, you can 
visualize the flow of statement execution as being a straight line through the program listing. 
Although linear flow seems very elementary, always remember that this is the computer's normal 
mode of operation. Even experienced programmers are sometimes embarrassed to discover that 
a "bug" in their program was due to the program linearly flowing into a portion of the program 
that was not supposed to be executed. 

Types of Program Flow 

As stated in the introduction of this chapter, a computer would be little more than a glorified 
adding machine if it were limited to linear flow. Here are the three general categories of program 
flow: 

• Sequentially executed program segments (one after the other) 

• Selection of program segments (conditional execution) 

• Repetition of program segments (loops) 

In addition to capabilities in all three of these categories, your computer also has a powerful 
special case of selection, called event-initiated branching. The rest of this chapter shows how 
to use all of these types of program flow and gives suggestions for choosing the type of flow 
that is best for your application. 
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Sequences of Program Segments 

There are several types of sequences that the computer can use in executing program segments: 

• Linear flow (no changes to normal sequence) 

• Halting program execution 

• Simple branching (modifying the normal sequence) 

Linear Flow 

The simplest form of sequence is linear flow. The preceding section showed an example of this 
type of flow. Although linear flow is not at all glamorous, it has a very important purpose. Most 
operations required of the computer are too complex to perform using one line of BASIC. Linear 
flow allows many program lines to be grouped together to perform a specific task in a predictable 
manner. Although this form of flow requires little explanation, keep these characteristics in mind: 

• Linear flow involves no decision making. Unless there is an error condition, the program 
lines involved in this type of flow will always be executed in exactly the same order, 
regardless of the results of or arguments to any expression. 

• Linear flow is the default mode of program execution. Unless you include a statement 
that stops or alters program flow, the computer will always "fall through" to the next 
higher-numbered line after finishing the line it is on. 

Halting Program Execution 

One of the obvious alternatives to executing the next line in sequence is not to execute anything. 
There are three statements that can be used to block the execution of the next line and halt 
program flow: 

• END 

• STOP 

• PAUSE 

Each of these statements has a specific purpose, as explained in the following paragraphs. 
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STOP and END 

The "Program Development" chapter defined a main program as a list of program lines with 
an optional END or STOP statement on the last line. Marking the end of the main program is 
the primary purpose of the END statement; its secondary purpose is to stop program execution. 
When an END statement is executed, program flow stops and the program moves into the stopped 
(non-continuable) state. 

It is often necessary to stop the program flow at some point other than the end of the main 
program. This is another purpose of the END or STOP statements. A program can contain 
any number of STOP statements in any program context. When a STOP statement is executed, 
program flow stops and the program moves into the stopped (non-continuable) state. Also, if the 
STOP statement is executed in a subprogram context, the main program context is not restored. 
(Subprograms and context switching are explained in the chapter "User-Defined Functions and 
Subprograms".) 

As an example of the use of STOP and END, enter the following program. 

100 Radius=5 

110 Circum=PI*2*Radius 

120 PRINT INT(Circum) 

130 STOP 

140 Area=PI*Radius~2 

150 PRINT INT (Area) 

160 END 

When you execute RUN, the computer prints 31 on the display. This first execution of the RUN 
command caused linear execution of lines 100 thru 130, with line 130 stopping that execution. 
If you execute RUN again, the same thing will happen; the program does not resume execution 
from its stopping point in response to a RUN command. However, RUN can specify a starting 
point, so you can execute a command like RUN 140. The computer prints and then stops. This 
command caused linear execution of lines 140 thru 160, with line 160 stopping that execution. 
However, a RUN command also causes a pre-run initialization, which zeroed the value of the 
variable Radius 1 . 



See the subsequent section of this chapter called "A Closer Look at Program Execution" for an explanation of pre-run. 
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PAUSE 

A stopped program is not continuable. This leads up to the third statement for halting program 
flow. Replace the STOP statement on line 130 of the preceding program with a PAUSE statement, 
yielding the following program. 



100 


Radius=5 


110 


Circum=PI*2*Radius 


120 


PRINT INT(Circum) 


130 


PAUSE 


140 


Area=PI*Radius~2 


150 


PRINT INT (Area) 


160 


END 



Now execute RUN. The computer prints 31 on the display. Then execute C0NT. The computer 
prints 78 on the display. The purpose of the PAUSE statement is to temporarily halt program 
execution, leaving the program counter intact and the program in a continuable state. One 
common use for the PAUSE statement is in program troubleshooting and debugging. This is 
covered in the chapter "Program Debugging." Another use for PAUSE is to allow time for the 
computer user to read messages or follow instructions. 

It would be ridiculous to use a WAIT statement to try to anticipate the number of seconds required 
for these actions. Note that the WAIT statement causes a delay in program execution until the 
specified number of milliseconds has elapsed. The PAUSE statement gives freedom to the user 
to take as little or as much time as necessary. 

When C0NT is executed, the program resumes with any necessary input of file names and 
assignments. 

You can also pause a program by using an interrupt signal. The signal is generated when a key 
sequence assigned that function has been pressed. Usually this key sequence is 1 CTRL ] - [ C ] . See 
"Pausing and Continuing a Program" section of the Getting Started Guide for details. 
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Simple Branching 

An alternative to linear flow is branching. Although conditional branching is one of the building 
blocks for selection structures, the unconditional branch is simply a redirection of sequential flow. 
The keywords which provide unconditional branching are GOTO , GOSUB , CALL, and FN. The CALL 
and FN keywords invoke new contexts, in addition to their branching action. The term context 
refers to the fact that each subprogram and user-defined function has its own independent set 
of variables and line labels. This is a complex subject that is the topic of an entire chapter 
("User-Defined Functions and Subprograms"). This section discusses the use of GOSUB and GOTO 
for local branching. 

Using GOTO 

First, you should be aware that it desirable to avoid the excessive or unnecessary use of the 
unconditional GOTO. The problem is not anything inherent in the GOTO statement. The problem 
lies in some programmers' tendencies to "patch together" pieces of a poorly planned algorithm, 
using more and more GOTOs with each revision. Then comes that inevitable day when a fatal bug 
reveals that it is impossible to "GET BACK FROM" the last "GO TO". A program that contains 
sloppy and excessive use of GOTO has been appropriately named spaghetti code. Keep this very 
descriptive term in mind when you are deciding whether to "just throw something together" or 
to take a little more time to organize and plan a project. 

The only difference between linear flow and a GOTO is that the GOTO loads the program counter 
with a value that is (usually) different from the next-higher line number. The GOTO statement can 
specify either the line number or the line label of the destination. The following drawing shows 
the program flow and contents of the program counter in a program segment containing a GOTO. 




Program Lines 



Value in Program Counter 
at End of Line 



180 


R = R + 2 

A rea=PI*R-2 

GOTO 240 

Width=Width+l 

L e n sf t h = L e n 1 1 h + 1 

Area=Width*LenSth 

PRINT "Area ="iflrea 

GOTO 210 


190 | 


190 


200 | 


2 


240 | 


210 


220 


220 


230 | 


230 


240 [ 


240 


250 ] 


250 


210 | 



As you can see, the execution is still sequential and no decision making is involved. The first 
GOTO (line 200) produces a forward jump, and the second GOTO (line 250) produces a backward 
jump. A forward jump is used to skip over a section of the program. An unconditional backward 
jump can produce an infinite loop. This is the endless repetition of a section of the program. 
In this example, the infinite loop is lines 210 thru 250. 
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An infinite loop by itself is not a desirable program structure. However, it does have its place 
when mixed with conditional branching or event-initiated branching. Examples of these structures 
are given later in this chapter. 

Using GOSUB 

The GOSUB statement is used to transfer program execution to a subroutine. Note that a 
subroutine and a subprogram are very different in Technical BASIC. Calling a subprogram invokes 
a new context; subprograms can declare formal parameters and local variables. A subroutine is 
simply another segment of the current program context that is entered with a GOSUB and exited 
with a RETURN. There are no parameters passed and no local variables. If you are a newcomer 
to Technical BASIC, be careful to distinguish between these two terms. They have been used 
differently in some other programming languages. 

The GOSUB statement is very useful in structuring and controlling program flow. GOSUB executes 
a branch to a subroutine, which performs a certain task or tasks. When those task are complete, 
control returns to the main body of the program. The GOSUB statement can specify either the 
line label or the line number of the desired subroutine entry point. The following drawing shows 
the program flow and contents of the program counter in a program segment containing a GOSUB. 

Value in Program Counter Value in Program Counter 

Subroutine Program Lines at End of Line Program Lines at End of Line 



1000 PRINT ftreai"ssuare in." I 1010 I tt^ I 300 R = R+2 

1010 Cent=A rea*B .4516 [70201 IT^Vw. I 310 Area=PI*R' 



i^J 



1020 PRINT Cent ! "square cm" [ToW] I ^» 320 GOSUB 1000 

1030 PRINT ITolo] I ^^J* 330 W i d t h = Wi d t h + 1 

1040 RETURN r^3Q~] U^^ I 340 Len St h =Le n St h +1 

^ 350 



K 



P r S r a m continues 



Program execution is sequential and no decision making is involved. The main reason that a 
GOSUB is a more desirable action than a GOTO is the effect of the RETURN statement. The RETURN 
statement always returns program execution to the line that would have been executed if the 
GOSUB had not occurred. This is especially useful when using an event-initiated GOSUB. Since it 
is usually impossible to predict when a user might press a softkey (for example), it is usually 
impossible to predict what program line should be returned to at the end of a service routine. 
Note that softkeys are keys on your keyboard which are defined by their corresponding label on 
the display. By using GOSUB and RETURN, the computer does the work for you. There are more 
details on this use of GOSUB later in this chapter. 
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Another common advantage gained from the use of GOSUB is program economy resulting from 
the consolidation of common tasks. For example, assume that you are writing a page formatter 
program to neatly print letters, reports, etc. The actions taken at the end of each page might 
be such things as follows: 

1. Skip two blank lines 

2. Print the page number 

3. Update the page counter 

4. Print a form-feed 

5. Zero the line counter 

These end-of-page actions might be necessary at many places in the program. For example: in 
the new-page segment, in the conditional-page algorithm, in the normal line-printing segment, 
and in the end-of-file process. It would be wasteful duplication to repeat all those end-of-page 
steps every place they are needed. 

That kind of duplication also opens the door to updating problems. Suppose that you wanted 
to modify the end-of-page action to make it print line-feeds instead of a form-feed for the benefit 
of a printer that doesn't use form-feeds. If you had duplicated the end-of-page routine in five 
different places in the program (or was that six?), you will be doing five times as much typing 
to make the change, and you will probably miss a spot. 

The solution is a subroutine. For the sake of completeness in this example, the hypothetical 
end-of-page subroutine is shown below. 

540 End_page: ! 

550 PRINT USING "2/,K" ; Pagenumber 

560 Pagenumber=Pagenumber+l 

570 PRINT CHR$(12); 

580 Lines=0 

590 RETURN 
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There are no well defined rules to dictate when a program task should be a subroutine and when 
it should be in the linear flow. The following suggestions may help you decide. 

• A subroutine should have some identifiable task, such as opening a file, normalizing a 
variable, executing an end-of-page algorithm, decoding a keypress, parsing a string, and so 
forth. It is handy for a subroutine to "hide the details" of performing a task so that these 
details do not obscure the readability (and supportability) of the routine. 

• Decisions about subroutines are best made on a conceptual level. Although there 
is nothing wrong with accidentally discovering that you repeated ten lines which would 
make a good subroutine, it is better to identify the appropriateness of subroutines during 
planning. One question to ask yourself is, "Does it make sense to handle this task in a 
subroutine?" If it takes a dozen flags 1 to select all the variations that are needed from 
one usage of the subroutine to the next, then a subprogram is probably a cleaner solution. 
Lines of code that just happen to be repeated in several places are not necessarily good 
candidates for a subroutine. 

• There is no significant speed penalty for using a subroutine. The time required to 
process the GOSUB and RETURN is extremely small. If you are having trouble getting your 
application to run fast enough, it is doubtful that your problems will be solved by removing 
a couple of GOSUBs. In fact, the resulting loss of "readability" may actually make it more 
difficult to identify and correct the real problem in timing. 

• The "cross-over point" in line overhead is a subroutine that is only three lines long and is 
called from only two places in the program. In other words, it takes the same number of 
program lines to duplicate three lines as it does to stick a RETURN on the end of them and 
add two GOSUB statements. However, there is nothing "magical" about this observation. It 
does not mean that you shouldn't have a subroutine shorter than three lines, or that you 
should go around making a subroutine out of every three-line sequence you see repeated. 
It should simply make you aware of possible improvements that could be made if you see 
the same sequence repeated in several places in your program. 



System flags are system variables that you can use to keep track of information. For instance, you can use a flag to keep track of 
an operating mode by storing it as a numeric value: IF FLAG(l) THEN End_page. See the "Using System Flags" section of the 
"User-Defined Functions and Subprograms" for further information. 
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Selection of Program Segments 

The heart of a computer's decision-making power is the category of program flow called selection, 
or conditional execution. As the name implies, a certain segment of the program either is or 
is not executed according to the results of a test or condition. This is the basic action which 
gives the computer an appearance of possessing intelligence. Actually, it is the intelligence of 
the programmer which is remembered by the program and reflected in the pattern of conditional 
execution. 

An Example 

Consider a chemistry lab application as an example. There would be little use for a computer 
whose only function was to turn on a valve when a technician pressed "START" button. The 
technician might just as well turn the valve himself. However, if the computer turned on a valve 
when the "START" was pressed and turned off the valve when a specified pH level occurred, 
then it is performing a much more useful task. 

If the example is extended to include state-of-the-art remote-control valves and electronic pH 
measuring devices, the computer is now significantly out-performing the technician. In this 
example, (in spite of any fancy instrumentation) the quality that moved the computer from 
"useless" to "useful" was its ability to decide when to turn off the valve. It was the programmer 
(you) who actually specified the criteria for the decision. Those criteria were then communicated 
to the computer using conditional-execution program structures. As a result, the computer was 
able to repeat the programmer's intention with much greater speed and accuracy than a human. 

Types of Conditional Execution 

This section presents the conditional-execution statements according to various applications. The 
following is a summary of these groupings. 

1. Conditional execution of one segment. 

2. Conditionally choosing one of two segments. 

3. Conditionally choosing one of many segments. 
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Conditional Execution of One Segment 

The basic decision to execute or not execute a program segment is made by the IF . . . THEN 
statement. This statement includes a numeric expression that is evaluated as being either true 
or false. If true (non-zero), the conditional segment is executed. If false (zero), the conditional 
segment is bypassed. Although the expression contained in an IF . . .THEN is treated as a Boolean 
expression 1 , note that there is no BOOLEAN data type in BASIC. Any valid numeric expression 
is allowed. 

The conditional segment can be either a single BASIC statement or a program segment containing 
any number of statements. The first example shows conditional execution of a single BASIC 
statement. 

100 IF Ph>7.7 THEN PRINT "Ph is > 7.7." 

Notice the test (Ph>7.7) and the conditional statement (PRINT. . .) which appear on either side 
of the keyword THEN . When the computer executes this program line, it evaluates the expression 
Ph>7.7. If the value contained in the variable Ph is 7.7 or less, then the expression evaluates 
to (false) and the line is not executed. If the value contained in the variable Ph is greater 
than 7.7, then the expression evaluates as 1 (true) and the PRINT statement is executed. If you 
don't already understand logical and relational operators, refer to the chapter entitled "Numeric 
Computation" or the chapter entitled "String Computation". 

The same variable is allowed on both sides of an IF. . .THEN statement. For example, the 
following statement could be used to keep a user-supplied value within bounds. 

IF Number>9 THEN Number=9 

When the computer executes this statement, it checks the initial value of Number. If the variable 
contains a value less than or equal to nine, that value is left unchanged, and the statement is 
exited. If the value of Number is greater than nine, the conditional assignment is performed, 
replacing the original value in Number with the value nine. 



A Boolean expression can have one of two values: true (1), or false (0). 
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Prohibited Statements 

Certain statements are not allowed as the conditional statement in an IF. . .THEN statement. The 
disallowed statements are used for various purposes, but the "common demoninator" is that the 
computer needs to find them during prerun as the first keyword on a line. (A possible exception 
to this reasoning is REM, which is not allowed because it makes no sense to allow it. Comments 
certainly aren't executed conditionally. If comments are necessary on an IF . . . THEN line, the 
exclamation point can be used.) The following statements are not allowed in an IF . . . THEN 
statement. 

Keywords used in the declaration of variables: 



OPTION BASE 


COM 


DIM 


SHORT 


INTEGER 


REAL 



Keywords that define context boundaries: 

DEF FN FNEND 
SUB SUBEND 

Keywords that define program structures: 

FOR 

NEXT 

Keywords used to identify lines that are literals: 

DATA 

REM 

Conditional Branching 

Powerful control structures can be developed by using branching statements in an IF. . .THEN. 
Here are some examples. 

110 IF Free_space<100 THEN GOSUB Expand.file 
120 ! The line after is always executed 

This statement checks the value of a variable called Free_space, and executes a file-expansion 
subroutine if the value tested is not large enough. The same technique can be used with a CALL 
statement to invoke a subprogram conditionally. One important feature of this structure is that 
the program flow is essentially linear, except for the conditional "side trip" to a subroutine and 
back. This is illustrated in the following drawing. 



3-12 Program Structure and Flow 



P_flag = 1 P_flag = 



1000 PRINT Area! "square 

1010 Cent=Area*G.451S 

1020 PRINT Cent ^'square 

1030 PRINT 

1040 RETURN 



>|r > f 



300 R=R+2 

310 Area=PI*R"2 

320 IF P_flaS THEN GOSUB 1000 

330 Width=Width+l 

340 Leris(th = Leri <Jth + l 



The conditional GOTO is such a commonly used technique that the computer allows a special 
case of syntax to specify it. Assuming that line number 200 is labeled "Start", the following 
statements will all cause a branch to line 200 if X is equal to 3. 

IF X=3 THEN GOTO 200 
IF X=3 THEN GOTO Start 
IF X=3 THEN 200 
IF X=3 THEN Start 

When a line number or line label is specified immediately after THEN, the computer assumes a 
GOTO statement for that line. (This improves the readability of programs, because phrases like 
"then start" sound more like English and less like computer jargon.) If execution is redirected 
by a conditional implied GOTO, then the program flow does not automatically return to the line 
following the IF . . . THEN. Thus, a conditional GOTO acts like a switch on a railroad track. This is 
illustrated in the following drawing. 



HOC 

11 1C 

11 

1 130 
1 140 



Record: ! 
! Test for open file 
! Do any CREATE* ASSIGN* etc, 
OUTPUT @File 5Text$ 
! Continue with file operation 



File 



550 Send_texts ! 

5G0 IF File THEN Record 

570 PRINT Text* 

580 Lines=Li nes+1 

590 ! C o n t i n u e with p r i n t i n 3 i 



Multiple-Line Conditional Segments 

If the conditional program segment requires more than one statement, a slightly different structure 
is used. Let's expand the valve-control example. 

100 ! This is a multiple-line IF... THEN structure. 

110 IF Ph<=7.7 THEN GOTO Skip 

120 PRINT "Ph is > 7.7" 

130 PRINT "Final Ph = ";Ph 

140 PRINT "Conditional Test Ends" 

150 Skip: ! Execution resumes here. 
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Any number of program lines can be placed between the line containing the IF . . . THEN statement 
(line 110 here) and the line number specified in the GOTO (line 150 here). In executing this 
example, the computer evaluates the expression Ph<=7.7 following the IF clause. If the result 
is true, then the program counter is set to 150 (i.e., the GOTO is executed), and execution resumes 
with that line. If the condition is false, the program counter is set to 120 (i.e., the GOTO is not 
executed), and the "conditional" statements (lines 120, 130, and 140) are executed. Line 150 
is then where "normal" execution resumes. 

If an other branching construct is used within a multiple-line IF . . . THEN structure, the entire 
structure should be contained in the conditional segment. This is called nesting constructs. The 
following example shows some properly nested constructs. Notice that the use of indenting 
improves the readability of the otherwise messy code. 

100 PRINT "Enter an integer value between 1 and 5." 

110 INPUT Value 

120 IF Value<=l THEN GOTO NotGrThanl 

130 ! Begin outer IF. 

140 PRINT "Value is greater than 1." 

150 IF Value>=5 THEN NotLsThan5 

160 ! Begin nested IF. 

170 PRINT "Value is less than 5." 

180 NotLsThan5: ! End of nested IF. 

190 ! 

200 NotGrThanl: ! End of outer IF. 

210 END 

Choosing One of Two Segments 

This language has an IF . . . THEN . . . ELSE construct which makes the one-of-two choices easy 
and readable. The following example looks at a device selector which may or may not contain a 
primary address. The variable Isc is needed later in the program and must be only an interface 
select code. If the operator-supplied device selector is greater than 31, the interface select code 
is extracted from it. If it is equal to or less than 31, it already is an interface select code. (This 
example assumes that no secondary addressing is used.) 

500 IF Select>31 THEN Isc=Select DIV 100 ELSE Isc=Select 

Notice that this structure requires you to type the IF . . . THEN . . . ELSE structure on one contiguous 
line, which is not easy to read. Note that you may place multiple statements after the THEN and 
ELSE in this construct, as long as they are concatenated by the @ character. For example: 

IF X > 5 THEN X=X+5 @ DISP X ELSE X=X~2 @ DISP X 
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This is one way of implementing multiple statements within the IF. . .THEN. . .ELSE construct. 
However, one contiguous line of 159 characters is not easy to read. A more readable way to 
implement the choice between one of two segments is as follows: 

100 ! Choosing one of two segments. 

110 IF X>5 THEN GOTO Segl ELSE GOTO Seg2 

120 Segl: 

130 X=X+5 

140 DISP X 

150 GOTO CommonExit 

160 Seg2: 

170 X=X~2 

180 DISP X 

190 CommonExit: ! Both segments "continue" here. 

200 END 

Choosing One of Many Segments 

This requires chosing from one of several possibilities, and is like executing a sequence of 
IF. . .THEN statements. This type of program flow can be generated with the ON statement 
and some additional processing. Consider as an example the processing of readings from a 
voltmeter. In this example, we assume that the reading has already been entered, and it 
contained a function code. These hypothetical function codes identify the type of reading and 
are shown in the following table. 

Table 3-1. Function Codes 



Function Code 


Type of Reading 


DV 


DC Volts 


AV 


AC Volts 


DI 


DC Current 


AI 


AC Current 


OM 


Ohms 



Using the ON. . .GOSUB statement, all the anticipated values are placed in a simple string. This 
string is then searched using the POS function. The results of the POS function are adjusted 
to become consecutive integers beginning with one. This result can then be used in the ON 
statement. 



100 
110 
120 
500 
510 
520 



Mat ch$= " D VAVD I AI 0M " 



Pointer=P0S (Match$ ,UPC$ (Funct$) ) 

Pointer=INT((Pointer-l)/2+l) 

ON Pointer+1 GOSUB Case_else,Case_DV,Case_AV,Case_DI,Case_AI,Case_OM 
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Notice that a match can only cause values of 1, 3, 5, 7, or 9 from the POS function. The POS 
function returns the position of the first character of a substring within another string. A "match 
not found" gives a value of 0. Line 510 converts these to consecutive integers from thru 5. 
The Pointer+1 expression in line 520 shifts the values to a range 1 thru 6, which is acceptable 
to the ON statement. 

The values of the match characters will determine the "pre-processing" necessary. If you are 
trying to match single bytes, simply adding one to the results of the POS is all that is necessary. 
Finding 3-letter sequences requires a line like 510, but with a division by 3. Note also that, 
except for single bytes, this method may not always work. For example, if the current ranges 
had been indicated by DA and AA (instead of DI and AI), Match$ would be "DVAVDAAAOM". A 
subsequent search for "AA" would return 6 instead of 7 — not good. In a case like that, there 
are two choices. One approach is to rearrange the string being searched; "DVAVDAOMAA" 
would work. Perhaps the items in the string could be separated with a "pad" character and the 
calculation adjusted accordingly. The other approach is to make each match value a separate 
element of a string array. The array could then be "searched" with a FOR . . . NEXT loop. This 
approach works well to resolve conflicts, especially with long match strings. However, the extra 
code lines and array accesses slow the process down significantly. 

The ON statement can also be used for numeric values. If the numeric values you are trying to 
match just happen to be consecutive integers starting with one, the variable to be tested can be 
used in the ON statement. However, programmers are not usually that lucky. To match arbitrary 
values, the following trick can be used. This example tests the three cases: <0, 1, and >1. 

100 DISP "Enter an integer X." 

110 INPUT X 

120 Point er=l* (X<0) +2* (X=l) +3* (X>1) 

130 ON Pointer GOSUB Negative, One, Greater 

140 Negative: 

150 DISP "The value entered is negative." 

160 GOTO Quit 

170 One: 

180 DISP "The value entered is a positive 1." 

190 GOTO Quit 

200 Greater: 

210 DISP "The value entered is positive." 

220 GOTO Quit 

230 Quit: END 

Assuming that you use non-overlapping comparison tests, only one of the values in parentheses 
will be true. The system returns a value of "1" for true. This is multiplied times the corre- 
sponding factor to give the final value to Pointer. All the other factors drop out because their 
comparison result is zero. Programmers who like strong type checking may raise an eyebrow at 
this technique, but it works. 
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Another useful trick for testing for numbers that are integers between and 255 is to use the 
CHR$ function to create string bytes and apply the POS function as explained previously. The 
code lines for this are left as an exercise for the reader. 



Repetition 



Humans usually prefer tasks with variety that avoid tedious repetition. A computer does not 
have this shortcoming. Although a computer is usually a miserable failure at creative thought, 
it is in full glory when called upon to accurately repeat the same boring task millions of times. 

With Technical BASIC, you have only one structure available for creating repetition. However, 
the others can be built using the GOTO statement. 

This section covers the repetitive capabilities common to all versions of BASIC and explains how 
you can implement them using Technical BASIC. These capabilities are: 

• Repeating a program segment a predetermined number of times (using the FOR. . .NEXT 
construct) 

• Repeating a program segment indefinitely (using the GOTO statement), waiting for a specified 
condition to occur 

• Creating an iterative structure that allows multiple exit points at arbitrary locations (using 
the GOTO statement) 
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Fixed Number of Iterations 

The general concept of repetitive program flow can be shown with the FOR . . . NEXT structure, 
available in all BASIC language systems. With this structure, a program segment is executed 
a predetermined number of times. The FOR statement marks the beginning of the repeated 
segment and establishes the number of repetitions. The NEXT statement marks the end of the 
repeated segment. This structure uses a numeric variable as a loop counter. This variable is 
available for use within the loop, if desired. The following drawing shows the basic elements of 
a FOR. . .NEXT loop. 





STARTING 






VALUE 






LOOP 


FINAL 


STEP 




COUNTER 


VALUE 


SIZE 




, ** ., r**-^ r ^- > 


r**-^ 


2 


FOR Courit = 10 TO STEP 


-1 


210 


BEEP 




220 


PRINT Count 




230 


WAIT 1 




240 


NEXT Count 







REPEATED 
SEGMENT 



The number of loop iterations is determined by the FOR statement. This statement identifies 
the loop counter, assigns a starting value to it, specifies the desired final value, and determines 
the step size that will be used to take the loop counter from the starting value to the final 
value. When the loop counter is an INTEGER, the number of iterations can be predicted using 
the following formula: 



INT 



StepSize + FinalV alue — StartingValue 



StepSize 

Note that the formula applies to the values in the variables, not necessarily the numbers in the 
program source. For example, if you use an INTEGER loop counter and specify a step size of 0.7, 
the value will be rounded to one. Therefore, 1 should be used in the formula, not 0.7. Note 
also that the step size is a default of 1 when it is not included in the FOR . . . NEXT statement. 



The loop counter can be a REAL number, with REAL quantities for the step size, starting, or final 
values. In some cases, using REAL numbers will cause the number of iterations to be off by one 
from the preceding formula. This is because of inaccuracy in the comparison of REAL numbers. 
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If you are interested, this is discussed in the next chapter. However, there is no "clean" way 
around it with FOR. . .NEXT loops. Here is an example: 



200 


Count er=0 


210 


FOR X=10 TO 20 


220 


Count er=Count er+ 1 


230 


PRINT Counter 


240 


NEXT X 


250 


END 



According to the formula, this loop should execute 11 times: INT((l+20— 10)/1 = 11). The 
result on the display confirms this when the loop is executed. If line 210 is changed to: 

210 FOR X=l TO 2 STEP .1 

the formula still yields 11 as the number of iterations. However, executing the loop produces 
only 10 repetitions. This is because of a, very small accumulated error that results from the 
successive addition of one-tenth. The error is less significant than the 15th digit, but discernible 
to the computer. In this case, rounding cannot be performed at a time that would help. When 
you find yourself in this situation, one way out is to shift the final value very slightly. 

The following line does give the 11 iterations predicted by the formula. 
210 FOR X=l TO 2.0001 STEP .1 

Remembering the "increment and compare" operation at the bottom of the loop is helpful. After 
the loop counter is updated, it is compared to the final value established by the FOR statement. 
If the loop counter has passed the specified final value, the loop is exited. If it has not passed 
the specified final value, the loop is repeated. The loop counter retains its exit value after the 
loop is finished. This is not necessarily one full step past the final value. For example: 

FOR 1=1 TO 9.9 

This statement establishes a loop that executes nine times (the default step size is one). The 
variable I has the value 10 when the loop is exited. 

FOR Count=12 TO 1 STEP -0.3 

This statement establishes a loop that executes 37 times. The variable Count has the value .9 
when the loop is exited. Notice that negative step sizes are allowed using the same keywords 
as positive step sizes. 
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Some final points to mention concern the execution of the FOR statement. If any variables are 
present to the right of the equal sign, the value used is the value they have when the FOR 
statement is executed. Remember that the FOR statement is only executed once before the loop 
begins. Also, if the number of iterations evaluates to zero or less, the loop is not executed and 
program execution goes immediately to the line following the NEXT statement. 

Conditional Number of Iterations 

The FOR. . .NEXT loop produces a fixed number of iterations, established by the FOR statement 
before the loop is executed. Some applications need a loop that is executed until a certain 
condition is true, without specifically stating the number of iterations involved. Consider a 
very simple example. The following segment asks the operator to input a positive number. 
Presumably, negative numbers are not acceptable. A looping structure is used to repeat the 
entry operation if an improper value is given. Notice that it is not important how many times 
the loop is executed. If it only takes once, that is just fine. If the operator takes ten tries 
before he realizes what the computer is asking for, so be it. What is important is that a specific 
condition is met. In this example, the condition is that a value be non-negative. As soon as that 
condition has been satisfied, the loop is exited. 

800 Repeat: 

810 DISP "Enter a positive number." 

820 INPUT Number 

830 ! INPUT "Enter a positive number" .Number 

840 IF Number<0 THEN Repeat ! Until Number>=0 

1000 ! 

1010 DISP "Now this wasn't so bad." 

1020 END 

A typical use of this is an iterative problem involving non-linear increments. One example is 
musical notes. Performing the same operation on all the notes in a 3-octave band is a repetitive 
process, but not a linear one. Musical notes are related geometrically by the 12th root of two. 
The following example simply prints the frequencies involved, but your application could involve 
any number of operations. 

1200 Note=110 ! Start at low A 

1210 Repeat: 

1220 DISP "Enter a positive greater than 100." 

1230 INPUT Note 

1240 PRINT Note; 

1250 Note=Note*2~(l/12) 

1260 IF Note<880 THEN Repeat ! End at high A 

2000 ! 

2010 DISP "It's getting better; not much." 

2020 END 
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For this example, a FOR. . .NEXT loop might have been used, with the loop counter appearing 
in an exponent. That would work because it is relatively easy to know how many notes there 
are in three octaves of the musical scale. However, the Repeat. . .Until structure implemented 
with the IF . . . THEN and GOTO statements is more flexible than FOR . . . NEXT when working with 
exponential data in general. 

The While. . .End While loop structure, which executes from one to N number of statements 
several times until the loop condition is met, is used for the same purpose as the Repeat . . .Until 
loop structure and is implemented using the GOTO statement 1 . 

The only difference between the two is the location of the test for exiting the loop. The Repeat 
structure has its test at the bottom (post-test). This means that the loop is always executed 
at least once, regardless of the value of the condition. The While structure has its test at the 
top (pre-text). Therefore, it is possible for the loop to be skipped entirely (if the conditions so 
dictate). 

The Repeat. . .Until and While. . .End While structures are especially useful for tasks that are 
impossible with a FOR. . .NEXT loop. One such situation is a loop where both the loop counter 
and the final value are changing. Consider the example of stripping all control characters from a 
string. This can't be done in a loop that starts FOR 1=1 TO LEN(A$), because the length of A$ 
changes each time a character is deleted. Therefore, the loop counter used as a subscript will 
eventually exceed the length of the string by more than one, generating an error. The While 
loop structure does not have this problem. Note that the test at the top of the loop prevents 
the subscripting from being attempted on a null string. This is necessary to avoid an error. 

100 1=1 

110 While: ! KLEN(Str$) 

120 IF I>LEN(Str$) THEN End.While 

130 IF Str$[I,I]<CHR$(32) THEN Remove ELSE 1=1+1 @ GOTO While 

140 Remove: LastChar=LEN(Str$) 

150 Str$[I,LastChar-l]=Str$[I+l,LastChar] ! Remove Ctrl. char. 

160 Str$=Str$[l,LastChar-l] ! Remove trailing character. 

170 GOTO While 

180 EndjAfhile: 



Keep in mind that the Repeat . . . Until and While . . . End While keywords are not implemented in Technical BASIC. 

Program Structure and Flow 3—21 



Arbitrary Exit Points 

A pass through any of the loop structures discussed so far included the entire program segment 
between the top and the bottom of the loop. There are times when this is not the desired 
program flow. One alternative is to place a conditional GOTO in the middle of the loop that 
directs program flow to a point beyond the bottom of the loop. In fact, with Technical BASIC, 
this is the way it is accomplished. 

For the first example, consider a search and replace operation on string data. In this example, 
the "shift out" control character is being used to initiate underlining on a printer that understands 
standard escape sequences. The "shift in" control character is used to turn off the underline 
mode. (There is nothing significant about this choice of characters, any combination of characters 
could serve the same purpose.) 

One approach is to use a loop to search every character in every string to see if it is one of the 
special characters. There are two problems with this method. First, it is a little cumbersome 
when the replacement string is a different length than the target string. Second, it is slow. 
Admittedly, speed is not a significant consideration when driving common mechanical printers, 
but the destination might eventually be a laser printer or mass storage file, making the program's 
speed more visible. 

A better approach is to use the POS function to locate the target string. Since this function 
locates only the first occurrence of a pattern, it must be placed in a loop to insure that multiple 
occurrences will be found. The generalized Loop structure is well suited to this task, as shown 
in the following example. 

2000 Loopl: 

2010 Position=P0S(A$,CHR$(14)) 

2020 IF NOT Position THEN GOTO End.Loopl ! "Exit Loopl" 

2030 A$ [Position] =CHR$ (27)&"&dD"&A$ [Position+1] 

2040 GOTO Loopl 

2050 End.Loopl: 

2060 ! 

2070 Loop2: 

2080 Posit ion=P0S(A$,CHR$( 15)) 

2090 IF NOT Position THEN GOTO End_Loop2 

2100 A$ [Position] =CHR$ (27) &"&d@"&A$ [Position+1] 

2110 GOTO Loop2 

2120 End_Loop2: 

In this segment, all occurrences of "shift out" are replaced by "escape &dD" to enable underline 
mode. All occurrences of "shift in" are replaced by "escape &d@" to disable underlining. Notice 
that there is no problem replacing one character with four (assuming that A$ is large enough). 
Lines containing no special characters are processed by only two POS functions, which is much 
faster and cleaner than performing two comparisons for every character in every line. 
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Another common use for this structure is the processing of operator input. Recall the Re- 
peat. . .Until structure that tested for the input of a positive number. Although this structure 
kept the computer happy, it left the operator in the dark. The Loop structure provides for the 
additional processing needed, as shown in the following example. 

200 Loop: 

210 DISP "Enter a positive number . " 

220 INPUT Number 

230 IF Number>=0 THEN End.Loop 

240 BEEP 

250 PRINT 

260 PRINT "Negative numbers are not allowed." 

270 PRINT "Repeat entry with a positive number." 

280 GOTO Loop 

290 End.Loop: END 

Another point to remember is that the Loop structure permits more than one exit point. This 
allows loops that are exited on a "whichever comes first" basis. Also, the exiting can occur at 
the top or bottom of the loop. This means that the Loop structure can serve the same purposes 
as the Repeat and While structures, if that suits your programming style. 
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Event-Initiated Branching 

Your computer has a special kind of program flow that provides some very powerful tools. This 
tool, called event-initiated branching, uses interrupts to redirect program flow. Interrupts are 
conditions declared in a program that are constantly being monitored by the computer. When 
these particular conditions occur a branch is made from the normal program flow. 

The process can be visualized as a special case of selection. Every time program flow leaves 
a line, the BASIC system executes an "event-checking" subroutine. The process of "event 
checking" is represented in the following lines. 

10 PRINT X (gosub event_check) 
20 X=X+1 (gosub event_check) 
30 GOTO 10 (gosub event_check) 

Notice that it is possible for event-initiated branching to occur at the end of any program line, 
which includes the lines of a subprogram. These potential branching points are marked in the 
above BASIC program by the words "gosub event_check". These event checks are "if... then" 
statements that the BASIC system executes. If an event is enabled to initiate a branch (such as 
with ON KEY#) and the event occurs, then this "event-checking" routine initiates a branch to the 
service routine for the event (which you have designated in BASIC). 

Notice that in the sample program above if the operating system finds a "true" event, a branch 
is taken at the end of the current line. If not, program execution resumes with the "normal" 
program flow. 

Types of Events 

Event-initiated branching is established by the ON-event statements. Here is a list of the statements 
that fall in this category: 

ON KYBD ON ERROR 

ON TIMERS ON KEY# 

ON TIMEOUT 

The ON ERROR statement is used to trap run-time errors by specifying a branch to an error- 
handling routine. This subject is discussed in the chapter called "Error Handling". 
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The ON KYBD and ON KEY# events pertain to various parts of the keyboard and are used to 
enhance the "human interface" of programs. ON KYBD enables an event-initiated branch to be 
taken when the specified key(s) is(are) pressed during program execution. The term enable 
means to turn on the particular interrupt condition so that the computer can start monitoring 
that condition. The ON KEY# statement is used to define and label the softkeys on your keyboard, 
and enables an event-initiated branch for them. 

The ON TIMEOUT events pertain to interfaces and I/O operations. ON TIMEOUT enables end-of- 
line branching when an interface timeout occurs on the specified interface. These topics are 
discussed in the HP-UX Technical BASIC I/O Programming Guide. 

ON TIMER# defines an end-of-line branch to be taken when the specified time interval has elapsed. 
Note that the OFF command of all keywords mentioned above cancels that command. Timers 
are discussed in the "Clock and Timers" chapter. 

An Example of Using Softkeys 

The best way to understand how event-initiated branches operate in a program is to sit down at 
the computer and try a few examples. Start by entering the following short program. 



100 


ON KEY# 1,' 


"Inc" 


GOSUB 


Plus 


110 


ON KEY# 5,' 


■Dec" 


GOSUB 


Minus 


115 


ON KEY# 4,' 


'Quit' 


1 G0SUE 


S Quit 


120 


KEY LABEL 








130 


! 








140 


Spin: DISP 


X 






150 


GOTO Spin 








160 


! 








170 


Plus: X=X+1 






180 


RETURN 








190 


! 








200 


Minus : X=X- 


-1 






210 


RETURN 








220 


Quit: END 
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Notice the various structures in this sample program. The ON KEY# statements are executed 
only once at the start of the program. Once defined, these event-initiated branches remain in 
effect for the rest of the program. (Disabling and deactivating are discussed later.) The program 
segment labeled "Spin" is an infinite loop. If it weren't for interrupts, this program couldn't do 
anything except display a zero. However, there is an implied IF. . .THEN at the end of lines 140 
and 150 because of the ON KEY action. This allows a selection process to occur. Either the 
"Plus" or the "Minus" subroutine can be selected as a result of softkey presses. These are normal 
subroutines terminated with a RETUEN statement. (In the context of interrupt programming, these 
subroutines are called service routines.) The following section of pseudo code shows what the 
program flow of the "Spin" segment actually looks like to the BASIC system. 

140 Spin: DISP X 

If Key# 1 pressed, then gosub Plus. 
If Key# 5 pressed, then gosub Minus. 

150 GOTO Spin 

This pseudo code is an over-simplification of what is actually happening, but it shows that the 
"Spin" segment is not really an infinite loop with no decision-making structure. Actually, most 
programs that use event-initiated branching to control program flow will contain what appears 
to be an infinite loop. That is the easiest way to "keep the computer busy" while it is waiting 
for an interrupt. 

Now run the sample program you just entered. Notice that the the screen displays an inverse- 
video label area. These labels are arranged to correspond to the layout of the softkeys. The 
labels are displayed when the softkeys are active and are not displayed when the softkeys are 
not active. Any label which your program has not defined is blank. The label areas are defined 
in the ON KEY# statement by typing a comma after the key number and the key label name inside 
of quotes. 

The starting value in the display line is zero, since numeric variables are initialized to zero at 
prerun. Each time you press [ k1 I 1 , the displayed value of X is incremented. Each time you press 
| k5 I 1 , the displayed value of X is decremented. This simple demonstration should acquaint you 
with the basic action of the softkeys. 

It is possible to make structures that are much more elaborate, with assignable priorities for each 
key, and keys that interrupt the service routines of other keys. There are many applications 
where priorites are not of any real significance, such as the example program running now. 
However, priorities will sometimes cause unexpected flow problems. For more information on 
priorities, read the "Branch Precedence Table" found in the HP-UX Technical BASIC Language 
Reference. 



Key labels differ slightly for the various computers that run Technical BASIC. For information on key labels, refer to your particular 
HP-UX Technical BASIC system's Getting Started Guide. 
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Deactivating Events 

Knowing how to "turn off" the interrupt mechanism is just as important as knowing how to 
enable it. Often, an event is a desired input during one part of the program, but not during 
another. You might use softkeys to set certain process parameters at the start of a program, 
but you don't want interrupts from those keys once the process starts. For example, a report 
generating program could use a softkey to select single or double spacing. This key should be 
disabled once the printout starts so that an accidental keypress does not cause the computer to 
abort the printout and return to the questions at the beginning of the program. On the other 
hand, you might want an "Abort" key that does precisely that. The important thing is that you 
decide on the desired action and make the computer obey your wishes. 

A key is deactivated, if it no longer has any influence on program flow. You can press a 
deactivated key all day long and nothing will happen. 

All the "ON-event" statements have a corresponding "OFF-event" statement. This is one way to 
deactivate an interrupt source. Here is a summary of the various "OFF-event" statements. 

• OFF ERROR deactivates interrupts resulting from run-time errors. If these events occur while 
deactivated, the program pauses and an error message is displayed. 

• OFF KYBD deactivates end-of-line branching previously enabled by an ON KYBD statement. 

• OFF KEY# deactivates interrupts from the softkeys. If a softkey is pressed while deactivated, 
it does nothing. 

• OFF TIMEOUT deactivates interrupts from interface timeouts. There is no such thing as a 
"timeout" when ON TIMEOUT is deactivated. 

• OFF TIMER* deactivates end-of-line branching for the specified timer. 
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The following example shows one use of OFF KEY# to disable the softkeys. 

100 Begin: 

110 ON KEY# l,"StpSz" GOSUB Step.size 



120 


ON KEY# 4, "Start" GOTO Process 


130 


ON KEY# 5, "Quit " GOTO Quit 


140 


KEY LABEL 


150 


I 


160 


Inc=l 


170 


DISP "Step Size = 1" 


180 


! 


190 


Spin: GOTO Spin ! Wait for keypress 


200 


! 


210 


Step.size: 


220 


Inc=Inc+l ! Change increment 


230 


DISP "Step Size = " ; Inc 


240 


RETURN 


250 


! 


260 


Process: 


270 


! OFF KEY# ! Deactivate first choices 


280 


! ON KEY# 8," ABORT" GOTO Leave 


290 


KEY LABEL 


300 


Number=0 


310 


FOR 1=1 TO 10 


320 


Number=Number+Inc 


330 


PRINT Number 


340 


WAIT 600 


350 


NEXT I 


360 


Leave: 


370 


OFF KEY# 8 ! Deactivate ABORT 


380 


PRINT ! End line 


390 


GOTO Begin ! Start over 


400 


! 


410 


Quit: END 
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A softkey is used to select a parameter for a small printing routine. Each press of | k1 I increments 
and displays the step size that will be used as an interval between the printed numbers. When 
the desired step size has been selected, [ k4 [ is pressed to start the printout. Enter and run this 
example. Notice that with line 270 and 280 commented out, the softkey menu, or label area, 
never changes. 

Now run the example again and press | k1 | or | k4 | while the printout is in progress. Notice that 
the keys are still active and produce undesired effects on the printing process. To "fix this bug", 
remove the exclamation point from line 270. This disables all the softkeys when the printing 
process starts. Notice that the softkey menu goes away when no sofkeys are active. This is a 
very handy feature while you are experimenting with interupts. It provides immediated feedback 
to indicate when interrupts are active and when they are not. 

Finally, remove the exclamation point from line 280. Now, the softkey menu appears during the 
printing process. However, the choices are different than at the start of the program. The keys 
used to select the parameter and start the process are not active, because they are not needed 
at this point in the program. 

The OFF KEY# statement can include a key number to deactivate a selected key. This was done 
in line 370. 
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Chaining Programs 

You may have had in the past a program which was quite large, and you wanted to reduce the 
amount of memory required to run the program. The Technical BASIC system allows a running 
program to load and run another program. This section explains this type of operation. 

General Features 

Chaining allows you to break up a program into smaller segments, loading and running only one 
segment at a time. 

If you need to pass information from the program currently running to the program being chained, 
you can use the COM statement to place the shared variables in a "common" storage area. All 
that is necessary is to insure that the COM declarations in both programs match, and use the 
CHAIN command to call the other program. 

A Simple Example 

The following three short programs illustrate chaining. (If you are going to type these programs 
into your computer for this example, note that you will need to STORE them, not SAVE them. 
CHAIN only works with files created by the STORE command.) 

10 REM ****************** Program#l **************************** 

20 PRINT n Program#l" 

30 CHAIN "Program#2" 

40 END 

10 REM ****************** Program#2 **************************** 

20 PRINT "Program#2" 

30 CHAIN "ProgramttS" 

40 END 

10 REM ****************** Program#3 **************************** 
20 PRINT "Program#3" 
30 END 

When Program#l is run, the following output is printed: 

Program#l 
Program#2 
Program#3 
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Program-to-Program Communications 

All variables not placed in "common storage" (i.e., declared by a COM statement) are scratched 
when the chained program is loaded. So if you want chained programs to communicate with 
one another, then you will need to declare variables with the COM statement. 

The preceding three programs have been modified to place four variables in COM, thereby pro- 
viding a means for the programs to communicate. Note that the variables can be accessed with 
different names as they are passed between programs. 

10 REM ****************** Program#lC **************************** 

20 COM A,B$[1] ,C,D 

30 A=l B$="x" C=3 D=4 

40 PRINT "Program#lC";A;B$;C;D 

50 CHAIN "Program#2C" 

60 END 

10 REM ****************** Program#2C **************************** 

20 COM T,Y$[1] 

30 COM C,D 

40 PRINT n Program#2C";T;Y$;C;D 

50 CHAIN "Program#3C" 

60 END 

10 REM ****************** Program#3C **************************** 

20 COM Q.R$[1] 

30 COM W,X 

40 PRINT "Program#3C" ;Q;R$;W;X 

50 END 

When Program#lC is run, the following output is printed: 

Program#lC 1x3 4 
Program#2C 1x3 4 
Program#3C 1x3 4 

This is a simplistic example; however, it does show the general tasks involved in chaining pro- 
grams. For further details about numeric and string variables, read the "Numeric Computations" 
and "String Manipulation" chapters, respectively. For further information about COM, read the 
"User-Defined Functions and Subprograms" chapter. 
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A Closer Look at Program Execution 

The normal running of a program is started by the RUN command. Before being able to run a 
program, however, the computer must make a "pre-run," during which it performs such tasks as 
allocating memory for variables and verifying that the line numbers specified in branch instructions 
(GOTO and GOSUB) actually exist. The computer then begins normal program execution, starting 
with the lowest numbered line in the main program. 

This section describes some of the things that are happening during prerun and while the program 
is being executed. You may skip this section with no loss of continuity if you are not interested 
in this level of detail. 

Prerun (RUN and INIT) 

Prerun is executed automatically by the RUN command. It is also executed by the INIT command, 
which allows you to perform a prerun without starting program execution — a handy operation 
to have for use with the SINGLESTEP command (see the "Program Debugging" chapter for details). 

There are three primary reasons for the prerun. 

• To reserve sufficient memory for all the variables in the program. This includes all variables 
in COM, DIM, INTEGER, SHORT, and REAL statements, and all implicitly declared variables. 
(The chapter entitled "Numeric Computation" explains the declaration of numeric variables, 
and the chapter "String Manipulation" covers the dimensioning of string variables.) 

• To detect errors that involve interaction between lines. The computer checks for syntax 
errors before it stores a program line. However, there are some errors that can't be 
detected by looking at a single line. For example, a program line that uses properly placed 
subscripts can appear to be correct when it is stored. However, if that line references two 
dimensions in an array that had previously been declared to have only one dimension, it 
is in error. To detect an error of that kind, the computer needs to "search" the entire 
program to see all the dimension statements as well as the variables used in each line. 
Another example of this kind of error is a GOTO or GOSUB that specifies a line that does 
not exist. 

• To locate all the user-defined function boundaries. These are defined by the DEF FN 
statement and the FNEND statement with multiple-line, user-defined functions. (See the 
"User-Defined Functions and Subprograms" chapter for a complete description of user- 
defined functions.) 

Note that these types of "prerun errors" are not caught by ON ERROR (discussed in the "Error 
Handling" chapter). 
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Normal Program Execution 

The term execution is used to describe the process used by the computer while it is completing 
the tasks described in its program. The process of program execution is summarized below. 

1. Determine which program line is to be acted upon next. 

2. Identify the statement that follows the line number and label (if any) on that line. 

3. If the statement has a run-time action, then perform that action. 

4. Repeat steps 1 thru 3 until an END, STOP, PAUSE or an error occurs. 

The continuing process of determining which line is to be executed next is discussed in detail in 
preceding sections of this chapter. The RUN command determines which line is acted on first. 
Executing RUN with no parameters, causes the execution process to begin at the first (lowest- 
numbered) line of the main program. Execution can be started anywhere in the main program 
by using the RUN command with a line identifier. For example: 

RUN 220 

This command causes execution to begin at line 220, if there is such a line. If there is no line 
220 in the main program, execution begins with the line whose number is closest to and greater 
than 220. 

Note that the prerun phase is always the same, whether the actual execution begins at the 
program start or somewhere in the middle. Also, if a starting line is specified, that line must 
be in the main program. An error 3 results when RETURN is executed if you attempt to start 
a program in a user-defined function or subprogram. Even if the starting point is correctly 
specified, be alert to the effects of starting a program in the middle. Skipping over a section of 
the program may result in null values for some of the variables. 
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Non-Executed Statements 

In the preceding summary of normal execution, step 3 mentioned that only statements with 
run-time actions are executed. The term run-time refers to the state that exists after the prerun, 
when the computer is actually performing the sequence of actions described by the program. 
Some statements are not executed in the course of normal program flow, but are merely "looked 
at" and then bypassed. 

The following is a list of some statements that do not cause an action as a result of run-time 
execution. 

• Comments and REM statements: these never cause an action. (See the "Program Develop- 
ment" chapter for more complete details.) 

• Variable declarations: COM, DIM, INTEGER, SHORT, and REAL. These are executed during 
prerun but skipped at run time. The OPTION BASE statement is also part of the declaration 
process. (See the "Numeric Computation"s and "String Manipulations" chapters for further 
descriptions of these statements.) 

• DEF FN and FNEND statements. These are used during prerun to establish the program 
structure and are skipped over at run time. (See the "User-Define Functions and Subpro- 
grams" chapter for a complete description.) 

• DATA statements: these are accessed by the READ statement, but are not executed. (See 
the "Data Storage and Retrieval" chapter for further information.) 
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Numeric Computation 



4 



Introduction 

When most people think about computers, the first thing that they think of is number-crunching 
— the giant calculator with a brain. Whether this is an accurate impression or not, numeric 
computations are an important part of computer programming. 

Numeric computations deal exclusively with numeric values. For instance, adding two numbers 
and calculating a sine or a logarithm are all numeric operations. Making numeric computations 
from the keyboard and within a program are covered in this chapter. 

Even though numeric computation includes converting a number to a string, and vice versa, these 
tasks are not described in this chapter; they are covered in the "String Manipulations" chapter. 
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Here are the major topics covered in this chapter. 
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Assigning Values to Variables 

One of the most fundamental numeric operations is the assignment operation, achieved with the 
LET statement. The LET statement originally required the keyword LET for BASIC interpreters, 
but Technical BASIC makes it optional. Thus, the following program lines are equivalent: 

100 LET A=A+1 
100 A=A+1 

However, when executing these statements from the keyboard, there is a difference: 

• A=A+1 is evaluated as a boolean expression. 

• LET A=A+1 is an assignment to the variable A. 

Unless you have declared otherwise, the data type of numeric variables in this example is REAL. 
This is the default data type of numeric variables. The next section discusses other numeric 
data types and shows how to declare the type of a variable. 

Numeric Variable Names 

The rules for naming simple numeric variables are as follows: the name can be up to 32 characters 
in length, and it may contain alphabetic (uppercase and lowercase) characters, decimal digits, 
and the underscore (_) character. The only restriction is that the first character must be a letter. 

Here are some examples: 

A 

AVeryDescriptiveVariableName 

Const22 

NumericResult 

al5 

z_coordinate 
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Numeric Data Types 

There are three pre-defined numeric data types in Technical BASIC: 

• INTEGER 

• SHORT 

• REAL 

Any numeric variable that is not explicitly declared an INTEGER or SHORT is implicitly declared 
to be of type REAL. 

REAL Numbers 

The range of REAL numeric variables is the largest range of numeric values. The largest value of 
a REAL variable is returned by the numeric INF (infinity) function, and the smallest positive value 
is returned by the EPS (epsilon) function. For a more complete description of the range on your 
system, see the Implementation Specifics appendix for your particular BASIC system. 

SHORT Real Numbers 

The range of SHORT numeric variables is less than that of REAL numbers. For an exact description 
of the range of REALs on your system, see your Implementation Specifics appendix. 

INTEGERS 

The range of INTEGER numeric variables is less than that of REAL and SHORT numbers. Also, 
INTEGERS are whole numbers, and cannot contain any fractional part. 

For an exact description of the range of INTEGERS on your system, see your Implementation 
Specifics appendix. 



Numeric Computation 4-3 



Declaring a Variable's Data Type 

The DIM, REAL, SHORT, and INTEGER statements are provided for explicitly declaring numeric 
variables: 

DIM SimpleReal,RealArray(4,5) 
REAL XCoord.YCoord, Voltage (4, 13) 
SHORT LogBaselO,Hours(52,7) 
INTEGER I, J, Days (5), Weeks (5 ,17) 

Each of the above statements declares both simple and array variables. 

• A simple variable can, at any given time, contain only a single value. 

• An array variable can contain multiple values, each of which is accessed by subscripts. 

With Technical BASIC, you can only define the upper bound of array subscripts; the current 
OPTION BASE is always defined to be the lower bound. Details on declarations of arrays and how 
to use them are provided in the subsequent "Arrays" section of this chapter. 

Implicit Type Declarations 

When a variable is used in a program without its type being previously declared (such as with 
SHORT or INTEGER), it is implicitly declared to be of type REAL. Even though you can use this 
feature to implicitly declare a REAL variable's type, it is better programming practice to explicitly 
declare all variables. As shown in the preceding example, the DIM statement may also be used 
to declare REAL variables. 
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Evaluating Scalar Expressions 

This section describes some additional details of how the computer evaluates scalar arithmetic 
expressions (as opposed to array expressions, which is discussed in the subsequent "Arrays" 
section). 

Arithmetic Hierarchy 

If you look at the expression 2+4/2+6, it can be evaluated in several ways: 

• 2+(4/2)+6 = 10 

• (2+4)/2+6 = 9 

• 2+4/(2+6) = 2.5 

• (2+4)/(2+6) = .75 

Computers do not deal well with ambiguity, so a hierarchy is used for evaluating expressions. 
These rules were made to eliminate any questions about the meaning of an expression. When the 
computer encounters a mathematical expression, an "expression evaluator" is called. If you do 
not understand the expression evaluator, you can easily be surprised by the value returned for a 
given expression. In order to understand the expression evaluator, it is necessary to understand 
the valid elements in an expression and the evaluation hierarchy (the order of evaluation of the 
elements). 

Six items can appear in a numeric expression: 

• Constants — represent numbers or strings with fixed value. 

• Variables — represent the value stored in the variable. 

• Operators — modify or perform operations on other elements in the expression. 

• Intrinsic numeric functions — represent numeric values. 

• User-defined numeric functions — represent numeric values. 

• Parentheses — used to modify the default arithmetic hierarchy. 
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The following table defines the hierarchy used by the computer in evaluating numeric expressions. 



Table 4-1. Math Hierarchy 



Precedence 



Operator 



Highest 



Lowest 



Parentheses: ( ) used to force the order of evaluation 
Functions: both user-defined and machine-resident 
Exponentiation: * 

The logical "Not" monadic operator: NOT 
Multiplication and division: * / MOD DIV 
Addition and subtraction, and monadic operators: + - 
Relational operators: <<= = >=><> 
Logical "And" operator: AND 

Logical "Or" operators: OR EXOR 



When an expression is evaluated, it is read from left to right; operations are performed as 
encountered, unless one of the following is encountered: 

• A higher precedence operation is encountered immediately to the right of the operation 
being evaluated. 

• The hierarchy is modified by parentheses. 

If the computer cannot deal immediately with the operation, it is stacked and the expression 
evaluator continues to read the expression until it encounters an operation it can perform. It is 
easier to understand if you see how an expression is actually handled. The following expression 
is complex enough to demonstrate most of what goes on in expression evaluation. 

A = 5+3*(4+2)/SIN(X)+X*(l>X)+FNNegl*(X<5 AND X>0) 



4—6 Numeric Computation 



In order to evaluate this expression, it is necessary to have some background information. We 
will assume that DEG has been executed, that X=90, and that FNNegl returns — 1. Evaluation 
proceeds as follows: 

5+3*(4+ 2)/SIN(X)+X*(l>X)+FNNegl*(X<5 AND X>0) 

5+3* 6/SIN(X)+X*(l>X)+FNNegl*(X<5 AND X>0) 

5+18/SIN(X)+X*(l>X)+FNNegl*(X<5 AND X>0) 

5+18=l+X*(l>X)+FNNegl*(X<5 AND X>0) 

5 + 18+X*(l>X)+FNNegl*(X<5 AND X>0) 

23+X*(l > X)+FNNegl*(X<5 AND X>0) 

23+X*0+FNNegl*(X<5 AND X>0) 

23 + 0+FNNegl*(X<5 AND X>0) 

23+FNNegl*(X<5 AND X>0) 

23+-l*(X < 5 AND X>0) 

23+-l*(0 AND X > 0) 

23+-l*(0ANDl) 

23+-1 *0 

23 + 

23 



Numeric Computation 4-7 



Operators 

There are three types of operators in BASIC: monadic, dyadic, and comparison. 

• A monadic operator performs its operation on the expression immediately to its right. 
The monadic operators are: + - NOT. 

Examples of usage: 

-5 

NOT True 

• A dyadic operator performs its operation on the two values it is between. The dyadic 
operators are: ~ * / MOD DIV + -<<= = >=> AND OR EXOR. 

Examples of usage: 

5+3 
Varl MOD Var2 Varl=44 

While the use of most operators is obvious from the descriptions in the Technical BASIC Language 
Reference, some of the operators have uses and side effects that are not always apparent. 
Examples of such subtleties for DIV and MOD are shown in the next section. 

DIV and MOD 

Two additional arithmetic operators are DIV (integer division) and MOD (modulo). These operators 
can be used exactly like the arithmetic operators previously discussed. 

The DIV operator uses this formula: 
A DIV B = IP(A/B) 

where IP returns the integer portion of the quotient of A/B. 

The MOD operator returns the remainder resulting from a normal division. Given two numbers, 
A and B, A MOD B is defined by the equation: 

A MOD B = A - B * INT(A/B) 
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where INT(A/B) is the greatest integer less than or equal to the quotient of A/B. It turns out 
that: 

0<=(A MOD B)<B if B>0 

and 

B<(A MOD B)<=0 if B<0. 

By definition, A MOD is A. 

Try the following arithmetic operations: 
Expression Result 



16 DIV 5 


3 


19 DIV 5 


3 


5 DIV 16 





5 DIV 6 





16 MOD 5 


1 


17 MOD 5 


2 


-8 MOD 3 


1 


(8 MOD 3) 


-2 



The expression I -8 MOD 3 is not evaluated the same way as I - (8 MOD 3) , because the monadic 
j - operator has a higher priority than the MOD operator. 

Expressions, Calls, and Functions 

All numeric expressions are passed by value to subprograms. Thus 5+X is obviously passed by 
value. Not quite so obviously, +X is also passed by value. The monadic operator makes it an 
expression. For more information on functions and subprograms read the chapter "User-Defined 
Functions and Subprograms". 
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Strings in Numeric Expressions 

String expressions can be directly included in numeric expressions if they are separated by 
comparison operators. For instance: 

A$="ABC" 

The comparison operators always yield "boolean" results, which are numeric values in BASIC. 
This numeric expression is 1 if the string variable names A$ is equal to the string ABC, and 
otherwise. 

Step Functions 

The comparison operators are obviously useful for conditional branching (IF. . .THEN statements), 
but are also valuable for creating numeric expressions representing step functions. For example, 
you can easily represent this function with a numeric expression: 

• IF Select<0 THEN Result=0 

• IF 0<=Select<l THEN Result=(A|2+B|2)~ lh. 

• IF Select>=l THEN Result=15 

It is possible to generate the required response through a series of IF . . . THEN statements, but 
it can also be done with the following expression: 

1210 Result=(Select<0)+(Select>=0 AND Select<l)*SQR(A"2+B~2)+ (Select>=l)*15 

While the technique may not please the purist, it actually represents the step function very well. 
The "boolean" (comparison) expressions each return a 1 or 0, which is then multiplied by the 
accompanying expression. Expressions not matching the selection return 0, and are not included 
in the result. The value assigned to Select before the expression is evaluated determines the 
computation placed in Result. This technique can be used to represent other functions, as long 
as the program statement does not exceed the maximum allowable line length. 
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Making Comparisons Work 

If you are comparing INTEGER numbers, no special precautions are necessary. However, if you 
are comparing REAL or SHORT values, especially those which are the results of calculations and 
functions, it is possible to run into problems due to rounding and other limits inherent in the 
system. For example, consider the use of comparison operators in IF . . THEN statments to check 
for equality in any situation resembling the following: 

120 DEG 

130 A=25. 3765477 

140 IF SIN(A)~2+C0S(A)~2=1 THEN PRINT "OK" ELSE PRINT "Not OK" 

You may find that the equality test fails due to rounding errors or other errors caused by the 
inherent limitations of finite machines. A repeating decimal or irrational number cannot be 
represented exactly in any finite machine. 

A good example of equality error occurs when multiplying or dividing data values. A product 
of two non-integer values nearly always results in more digits beyond the decimal point than 
exists in either of the two numbers being multiplied. Any tests for equality must consider the 
exact variable value to its greatest resolution. If you cannot guarantee that all digits beyond the 
required resolution are zero, there are three techniques that can be used to eliminate equality 
errors: 

• Use the value of the absolute difference between the two values, and test for the difference 
less than a specified limit. 

IF ABS(A-B)<.001 THEN DISP "Equal" ELSE DISP "Not Equal" 

• Use the absolute value of the relative difference between two values, and test for the 
difference less than a specified limit: 

IF ABS((A-B)/B)<.001 THEN DISP "Equal" ELSE DISP "Not equal" 

• Eliminate unwanted resolution before comparing results. For instance, you could use a 
specified number of significant digits in the comparison. 
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Range Limits 



It is sometimes necessary to limit the range of values that are assigned to a variable. You can 
do that with IF. . .THEN statements, as shown in these statements: 

200 IF X>MaxX THEN X = MaxX 
210 IF X<MinX THEN X = MinX 

However, it is more convenient to use the MAX and MIN functions. 

200 X = MAX (X, MinX) 
210 X = MIN (X, MaxX) 

Note that MAX is used to establish the lower bound, and MIN is used to establish the upper bound. 
If you think about it a minute, it makes sense. 

Here is a faster version of the above computation: 
190 X = MIN (MAX (X, MinX) , MaxX) 
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Rounding 

Rounding occurs frequently in computer operations. The most common rounding occurs in 
printouts and displays, where it can be handled effectively with a USING clause in an output 
operation. For instance: 

DISP USING "DD.DDD"; Number 

The value in the variable Number is displayed using (up to) two decimal digits preceding the 
decimal point radix, and three digits following the decimal point. For further details, see the 
"Formatting Information" section of the "Communicating with the Operator" chapter. This 
feature works in statements such as DISP , PRINT , LABEL, and OUTPUT . 

Sometimes it is necessary to round a number in a calculation in order to eliminate unwanted 
resolution. There are two basic types of rounding: 

• Rounding to a number of significant decimal digits 

• Rounding to a number of significant decimal places (limiting fractional information) 

Both types of rounding have their own application in programming. 

There is a tendency for the number of decimal places to grow as calculations are performed on 
the results of other calculations. One of the first things covered in training for engineering and 
the sciences is how to handle the growth of the number of decimal places in a calculation. If the 
initial measurements from an experiment produced three digits of information per reading, it is 
very misleading to produce a seven-digit number as the result of a long series of calculations. 

In rounding to a number of decimal places, the idea is to eliminate decimal representation beyond 
a specific power of ten. A simple approach to it is to shift the desired decimal information to the 
left of the radix, round up (add 0.5 to the resulting quantity), use INT to get rid of the undesired 
decimal information, then shift the number (to the right) back to its original position. 

180 X=123.456 

190 Places=2 ! Round to two digits after decimal point. 

200 ScaleFactor=10"Places 

210 XRounded=INT (X*ScaleFactor+0 . 5) /ScaleFactor 

220 DISP XRounded 

Here are the program's results: 
123.46 

ScaleFactor and Places should both be INTEGERS. The example shows rounding to 2 decimal 
places (to the right of the decimal point). Places should be set to a negative number to round 
to a number of digits to the left of the decimal point. 
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Binary Operations 

We humans usually think of numbers being represented as decimal numbers, so this is the default 
representation for most input and output operations (such as INPUT and DISP). However, all 
operations the computer performs use the binary number representation. You usually don't see 
this, because the computer changes decimal numbers you input into its own binary representation, 
performs operations using these binary numbers, and then changes them back to their decimal 
representation before it displaying or printing them. 

There are some operations available with Technical BASIC that deal with binary numbers. For 
example, the BINIOR function performs a bit-by-bit "inclusive or" operation on the two arguments, 
and returns the result: 

BINI0R(2,5) 
7 

When any of these operations are used, the arguments are first converted to INTEGER (if they 
are not already of this type) and then the specified operation is performed. Therefore it is best 
to restrict bit-oriented binary operations to declared INTEGERS. However, if it is necessary to 
operate on a REAL or SHORT, then you should make sure that the argument is not beyond the 
range of INTEGERS (to avoid an error). 

Resident Binary Functions 

In the following descriptions, the variable(s) shown in parentheses (such as Argl, NthBit, and 
Shift) signify that the function requires numeric argument(s), which can be any numeric expres- 
sion. 

Function Description 

BINAND(Argl,Arg2) Returns the bit-by-bit logical "AND" of the two arguments. 

BINCMP(Arg) Returns the bit-by-bit "complement" of the argument. 

BINE0R(Argl,Arg2) Returns the bit-by-bit exclusive "OR" of the two arguments. 

BINIOR(Argl ,Arg2) Returns the bit-by-bit inclusive "OR" of the two arguments. 

BIT (Arg, NthBit) Returns the state of bit NthBit of Arg. 

ROTATES (String$, Shift) Returns a string obtained by shifting the characters in the string 

argument String$ the number of positions specified by Shift, with 
wraparound. (Even though this is a string function, you may also 
find it useful for binary operations. See the "String Manipulations" 
chapter for details.) 
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Number-Base Conversions 

The computer treats all numeric values as decimal (base 10) quantities. However, it is often 
necessary to handle numbers represented in these number bases: 

• Binary (base 2) 

• Octal (base 8) 

• Hexadecimal (base 16) 

This section describes the functions that allow you to convert between these number bases. 

Converting from Decimal 

Technical BASIC provides resident functions for converting from decimal to binary, octal, and 
hexadecimal number bases. These functions are as follows: 

DTB$ Converts a decimal number to a binary string 
DT0$ Converts a decimal number to an octal string 
DTH$ Converts a decimal number to a hexadecimal string 

The DTB$ (Decimal-To-Binary) string function returns a string containing the base-2 representation 
of the decimal argument. For example, to find the binary representation of 15, use this function: 

DTB$(15) 

The following "32-bit" string value is returned: 
0000000000000000000000000000 1111 

The DT0$ (Decimal-To-Octal) string function returns a string containing the octal representation 
of the decimal argument. The following function call returns the octal string representation of 
decimal 15: 

DT0$(15) 

This string value is returned: 
00000000017 

The DTH$ (Decimal-To-Hexadecimal) string function returns a string containing the hexadecimal 
representation of the decimal argument. To find the hexadecimal value for 15, use the following 
function call: 

DTH$(15) 
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The following string value is returned: 
0OO0O0OF 

Converting to Decimal 

Technical BASIC also provides functions to convert numbers from binary, octal, and hexadecimal 
number bases to a decimal numeric representation. These functions are as follows: 

BTD Converts a binary string to a decimal number 
OTD Converts an octal string to a decimal number 
HTD Converts a hexadecimal string to a decimal number 

The BTD (Binary-To-Decimal) numeric function returns the decimal equivalent of the specified 
binary number (which is represented by a string expression). For instance, this function converts 
an "8-bit" string-binary number to a decimal numeric value: 

BTDC'lllllili") 

Here is the numeric value it returns: 
255 

The OTD (Octal-To-Decimal) numeric function returns the decimal equivalent of the specified octal 
number (which is represented by a string expression). For instance, this function converts a 
string-octal number to a decimal numeric value: 

OTD ("377") 

Here is the numeric value it returns: 
255 

The HTD (Hexadecimal-To-Decimal) numeric function returns the decimal equivalent of the speci- 
fied hexadecimal number (which is represented by a string expression). For example, this function 
converts an "16-bit" string-hexadecimal number to a decimal numeric value: 

HTD("ff") 

Here is the numeric value it returns: 
255 
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Trigonometric Functions 

Technical BASIC provides several functions for dealing with angles and angular measure: SIN, 
COS, TAN; CSC, SEC, COT; ASN, ACS, ATN, ATN2; DTR and RTD. Each function has a different 
purpose, as described subsequently; however, all deal with angles. The interpretation of the 
argument, and consequent value returned, is dependent on the angular unit of measure currently 
being used. 

• The default unit for all angular measure is radians. 
You can use the RAD statement to set this mode. 
(There are 2 7r radians in a circle.) 

• Degrees can be selected with the DEG statement. 
(There are 360 degrees in a circle.) 

• Grads can be selected with the GRAD statement. 
(There are 400 grads in a circle.) 

Radians may be re-selected by the RAD statement. 

It is a good idea to explicitly set a mode for any angular calculations, even if you are using the 
default (radian) mode. Subprograms inherit the angular mode from the context that calls it. And 
if the subprogram changes the mode, then the mode used in the calling context is not restored. 

Resident Trigonometric Functions 

In the following descriptions, the variable(s) shown in parentheses (such as Angle, and X) signify 
that the function requires numeric argument(s), which can be any numeric expression. 

Function Description 

ACS(Cosine) Returns the arccosine of an expression (I -1 |<Cosine| <1) as an angle in 

first or second quadrant. The resultant angle returned is dependent upon 
the current DEG/RAD/GRAD mode. 

ASN (Sine) Returns the arcsine of an expression (|-1 |<Sine|<l) as an angle in first 

or fourth quadrant. The resultant angle returned is dependent upon the 
current DEG/RAD/GRAD mode. 

ATN (Tangent) Returns the arctangent of an expression as an angle in first or fourth 

quadrant. The resultant angle returned is dependent upon the current 
DEG/RAD/GRAD mode. 

ATN2(Y,X) Returns the arctangent of Y divided by X (Y/X) in the proper quadrant. 

(X,Y) is the rectangular coordinate position of a point. The resultant angle 
returned is dependent upon the current DEG/RAD/GRAD mode. 
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COS (Angle) Returns the cosine of the angle specified by the expression. The interpre- 

tation of the specified angle is dependent upon the current DEG/RAD/GRAD 
mode. 

COT (Angle) Returns the cotangent of the angle specified by the expression. The inter- 

pretation of the specified angle is dependent upon the current 
DEG/RAD/GRAD mode. 

CSC (Angle) Returns the cosecant of the angle specified by the expression. The interpre- 

tation of the specified angle is dependent upon the current DEG/RAD/GRAD 
mode. 

DTR(DegreeAngle) Converts the specified angle expression from degrees to radians. The 
result returned is independent of the current DEG/RAD/GRAD mode. 

RTD(RadianAngle) Converts an angle expression from radians to degrees. (The value this 
function returns is independent of the current DEG/RAD/GRAD mode.) 

SEC (Angle) Returns the secant of the angle represented by an expression. The interpre- 

tation of the specified angle is dependent upon the current DEG/RAD/GRAD 
mode. 

SIN (Angle) Returns the sine of the angle specified by the numeric expression. The in- 

terpretation of the specified angle is dependent upon the current 
DEG/RAD/GRAD mode. 

TAN (Angle) Returns the tangent of the angle represented by an expression. The 

interpretation of the specified angle is dependent upon the current 
DEG/RAD/GRAD mode. 
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Random Numbers 

The RND numeric function returns a pseudo-random random number greater than or equal to 
and less than 1. 

RND 
0.0459608752708518 

Scaling 

Since many modeling systems require random numbers with arbitrary ranges, it may be necessary 
to scale the numbers. 

200 R=INT(RND*Range)+0ffset 
The above statement will return an integer between Offset and Offset+Range. 

A New Seed 

The random number generator is seeded with the a default value at system reset, power-on, 
SCRATCH, and pre-run. You can change the seed with the RANDOMIZE statement, which will give 
a new pattern of numbers. 

RANDOMIZE NewSeed 
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Miscellaneous Numeric Functions 

Technical BASIC provides a generous complement of numeric functions. For instance, the ABS, 
MIN, and MAX functions have been used in preceding examples. This section lists some of the 
general numeric functions which are not described elsewhere in this chapter. 

Resident General Numeric Functions 

In the following descriptions, the variable(s) shown in parentheses (such as Number and Arg) 
signify that the function requires numeric argument(s), which can be any numeric expression. 



Function Description 

ABS (Number) Returns the absolute value of the expression Number. 

CEIL (Number) Returns the smallest integer greater than or equal to the expression 

Number. 

EPS Returns the machine's "epsilon" — the smallest positive number 

greater than zero that the system can handle. Note that this is system- 
specific; refer to the Specifics appendix for you particular system. 

EXP(PowerOfE) Raise the natural e to the power specified by the expression PowerOfE. 

(e« 2.718 281828 459 05). 

FLOOR (Number) Returns the greatest integer that is less than or equal to the specified 

expression Number. (Same as INT function.) 

FP (RealNumber) Returns the "fractional" part of the specified expression RealNumber. 

INF Returns the machine's "infinity" — the largest positive number that 

the system can handle. This number is system-specific; refer to the 
Specifics appendix for you particular system. 

INT (Number) Returns the greatest integer that is less than or equal to the specified 

expression Number. The result is of the same type (INTEGER or REAL) 
as the original number. It differs from IP with negative numbers. For 
example: 



INT (-45. 66) 
IP (-45. 66) 



returns the value -46. 
returns the value -45. 



4-20 Numeric Computation 



IP (Number) Returns the integer part of the expression Number. (Similar to INT 

above.) 

LGT (Number) Returns the base 10 logarithm of the specified decimal expression 

Number. 

LOG (Number) Returns the natural logarithm (base e) of the specified decimal expres- 

sion Number. 

MAX (Argl, Arg2) Compares Argl and Arg2, and returns the larger of the two values. 

MIN(Argl,Arg2) Compares Argl and Arg2, and returns the smaller of the two values. 

NUM(String$) Returns the decimal code of the first character in the specified String$ 

expression. 

PI A constant function which returns a 15-digit approximation of 7r; 

3.141592 653 589 79. 

POS(Source$,Target$) Returns the position (index) of the Target$ string expression in the 
Source$ string expression. (See the "String Manipulations" chapter 
for examples.) 



RMD 
(Dividend , Divisor) 

SGN (Number) 



SQR(PositiveN) 

VAL (String$) 
VAL$ (Number) 



Divides Dividend by Divisor (Dividend/Divisor) and returns the re- 
mainder of the division (not the quotient, as in DIV). 

Returns the arithmetic sign of the expression Number: 1 if positive, 
if 0, —1 if negative. 

Returns the positive square root of the non-negative expression Posi- 

tiveN. 

Returns the decimal number represented by the string expression. 
Returns the string representation of the specified Number. 



Numeric Computation 4—21 



Arrays 

This section describes the broad topic of arrays. Here are the topics discussed in the remainder 
of this chapter: 

• Concepts — what is an array? ' 

• Creating an array variable — dimensioning. 

• Assigning value to individual elements. 

• Displaying arrays. 

• Redimensioning arrays. 

• Assigning values to all elements of an array. 

• Constant and zero matrices. 

• Identity matrices. 

• Copying subarrays. 

• Scalar arithmetic array operations. 

• Summing rows and columns. 

• Array transpose. ^ 

• Matrix multiplication. 

• Vector cross products. 

• Matrix inversion. 

• Solving systems of linear equations. 
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Array Concepts 

An array variable (or simply, an array) is a group of data items of one type, collectively referred 
to by one variable name. Subscripts enclosed in parentheses after the array name reference 
individual items in the collection. 

Technical BASIC allows one- and two-dimensional arrays. A one-dimensional array (also called 
a vector) can be thought of as a list of items consisting of several rows but only one column; 
items are referenced by one integer subscript. A two-dimensional array is like a table of items. 
The table has multiple rows and columns, and elements in the table are accessed by two integer 
subscripts separated by commas. 

The number of items, or elements, in an array is determined by the lower and upper bounds 
of its subscripts. The lower bound of an array subscript is the lowest value that the subscript 
can be assigned; the upper bound of an array subscript is the highest value subscript that the 
subscript can be assigned. For example, the following group of ten numbers can be organized 
several different ways: as one ten-item list; as two five-item lists; or as five two-item lists. 

1 2 

3 4 

5 6 

7 8 

9 10 

The following array is organized as one ten-item array. 

Numbers (0)=1 Numbers (1)=2 

Numbers (2) =3 Numbers (3) =4 

Numbers (4) =5 Numbers (5) =6 

Numbers (6) =7 Numbers (7) =8 

Numbers (8)=9 Numbers (9)=10 

The lower bound of the array subscript is 0, and the upper bound is 9. Non-integer subscripts 
are rounded to the nearest integer. Negative subscripts are not allowed. 

The following assignments treat the data as two five-item lists (i.e., two one-dimensional arrays 
of five elements each). 

OddNumbers(0)=l EvenNumbers(0)=2 

0ddNumbers(l)=3 EvenNumbers(l)=4 

0ddNumbers(2)=5 EvenNumbers(2)=6 

0ddNumbers(3)=7 EvenNumbers(3)=8 

0ddNumbers(4)=9 EvenNumbers(4)=10 
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Now organize the two lists as one two-dimensional array. The two subscripts used to reference 
the items are separated by commas; the first subscript designates the row, the second subscript 
designates the column. 

Numbers (0,0) =1 Numbers (0, 1) =2 

Numbers (1,0) =3 Number s ( 1, 1) =4 I 

Numbers (2,0) =5 Numbers (2, 1) =6 ' 

Numbers (3,0) =7 Numbers (3,1) =8 

Numbers (4,0) =9 Numbers (4, 1) =10 

The lower bound of both subscripts in the Numbers array is 0. Note that there are different 
upper bounds for each of the two subscripts: 4 and 1. 

The above examples used numeric arrays. The computer also allows string arrays; see the 
"String Manipulations" chapter for details. 

Dimensioning Arrays 

Dimensioning an array establishes the array-subscript upper bound(s) and reserves computer 
memory for the array elements. After a variable is dimensioned, you can reference the individual 
elements by using the array name and the appropriate subscript(s). Here is a simple example: 

100 DIM RealArrayO) ! Dimension the array. 

110 ! 

120 RealArray(0)=123 ! Assign value to element 0. ( 

130 RealArray(7)=3.142 ! Assign value to element 7. v 

140 ! Now display an element's value. 

150 DISP "Value of element 7 =" ;RealArray(7) 

Here are the program's results: 
Value of element 7 = 3.142 

Array Subscript Bounds 

The array in the preceding example had 10 elements, specified by the array subscripts through 
9. The upper bound (9) was specified in the DIM statement. The maximum upper bound of any 
numeric array subscript is 65 530. 

The lower bound of an array subscript, always or 1, is established either by default or explicitly. 
Technical BASIC assumes that all array subscripts have a lower bound of 0, unless you specify 
otherwise using this statement: 

OPTION BASE 1 ( 
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Since the computer assumes OPTION BASE unless told otherwise, the OPTION BASE statement 
is used only for documentation purposes. 

An OPTION BASE statement can be included only once in a program. Once an option base has 
been declared (or assumed), that option base is used throughout the program. The OPTION BASE 
declaration in a program must appear before any array variables are dimensioned or referenced. 
And you cannot execute an OPTION BASE statement from the keyboard after running a program. 

Declaration Statements 

These declarative statements are available for dimensioning arrays — declaring the type and 
size of the array: 

• REAL (and DIM) 

• SHORT 

• INTEGER 

• COM 

The DIM statement is used to declare REAL variables — both simple and arrays. The REAL 
statement is also used to dimension REAL variables; it is the preferred method, because it 
documents the variable's type more clearly. 

10 OPTION BASE 1 

20 REAL Light, Energy (20) ! Simple variable Light, and 

30 ! 20-element array Energy. 

All numeric variables in DIM statements, both simple and array, are assumed to be of type REAL. 
The only way to declare them to be of type INTEGER or SHORT is to explicitly declare them using 
the corresponding INTEGER or SHORT declaration statement. 

The SHORT statement declares simple numeric and numeric array variables of type SHORT. 

10 OPTION BASE 

20 SHORT Change(9, 15) .Delta, PSI ! 160-element array Change, 

30 ! and simple variables Delta and PSI. 

The INTEGER statement declares simple numeric or numeric array variables of type INTEGER. 

10 OPTION BASE 

20 INTEGER Day .Pointer (40) ! Simple variable Day, and 

30 ! 41-element array Pointer. 
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The COM statement can declare variables of any type. It is used to reserve memory in com- 
mon storage. Programs and subprograms use common storage for communicating with one an- 
other. Program-to-program communication is discussed in the "Chaining Programs" section of the 
"Program Structure and Flow" chapter. Subprogram-to-program and subprogram-to-subprogram 
communications are discussed in the "Program/Subprogram Communication" section of the 
"User-defined Functions and Subprograms" chapter. 

Implicit Dimensioning 

You need not dimension an array if its upper bounds are less than or equal to 10. Any array 
not explicitly dimensioned (such as with DIM) is assumed to have upper bound(s) of 10. Here 
are the number of elements that implicitly dimensioned arrays will have: 

One-dimensional Two-dimensional 

Array Array 



OPTION BASE 11 121 (11*11) 

OPTION BASE 1 10 100 (10*10) 

If you want an array to have fewer elements, you must dimension it explicitly. This also conserves 
memory by allocating space for fewer elements. 

Because of implicit dimensioning, the statement that explicitly dimensions an array variable must 
appear before any elements of the array are referenced. Otherwise, the system first dimensions 
the array implicitly and then reports an error when the second dimension is attempted (the explicit 
declaration) 1 . Here is an example that will generate Error 35 : DIM EXIST VRBL ("attempted 
to dimension an existing variable"): 

100 OPTION BASE 1 

110 Array(3)=44 ! Implicitly dimensions ' Array ( 10) ' . 

120 DIM Array (10) ! Causes error 35 (at pre-run) . 

Regardless of the method used to dimension an array, it can be dimensioned only once in a 
program. A second attempt to dimension an array variable generates this pre-run error (35). 



This error will be caught during program pre-run, which occurs at RUN and INIT. Pre-run is described in the section called "A Closer 
Look at Program Execution" in the "Program Structure and Flow" chapter. 
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Array Variable Names 

The rules for naming simple numeric variables also apply to numeric arrays. The name can be 
up to 32 characters in length, and may contain alphabetic (uppercase and lowercase) characters, 
decimal digits, and the underscore (_) character. The only restriction is that the first character 
must be a letter. 

In addition, a simple variable may be given the same name as an array variable. However, 
the simple variable is referenced using the name without subscripts, while an array element is 
referenced using one or two subscripts in parentheses. For example: 

Variable Simple numeric variable. 

Variable (2, 4) Element of a numeric array. 

Assigning Values to Individual Elements 

Here is an example of dimensioning an array, assigning values to its elements, and displaying 
the array elements individually: 

10 OPTION BASE 1 

20 DIM Squares (8) 

25 ! 

30 FOR Element=l TO 8 

40 Squares (Element) =Element*Element 

50 PRINT Element ; "times" ; Element ;"="; Squares (Element) 

60 NEXT Element 

70 END 

The program produces the following results: 



1 


times 


1 = 


1 


2 


times 


2 = 


4 


3 


times 


3 = 


9 


4 


times 


4 = 


16 


5 


times 


5 = 


25 


6 


times 


6 = 


36 


7 


times 


7 = 


49 


8 


times 


8 = 


64 
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Displaying and Printing Entire Arrays 

Preceding examples have shown how to display and print individual array elements. However, 
it is often easier to use some resident features of the Technical BASIC system to do that for 
you. There are two statements for displaying and for printing arrays: MAT DISP and MAT PRINT. 
MAT DISP displays the array on the current (CRT IS) screen, while MAT PRINT prints arrays on 
the current (PRINTER IS) system printer. 

Here are examples of using the MAT DISP and MAT PRINT statements: 

100 OPTION BASE 1 

110 REAL Array33(3,3) ! 3x3 array. 

120 ! 

130 DATA 11,12,13,21,22,23,31,32,33 

140 MAT READ Array33 

150 ! 

160 MAT DISP Array33, ! Trailing " , " means 21-col. fields. 

170 DISP 

180 ! 

190 MAT DISP Array33; ! Trailing " ; " means compact. 

200 DISP 

210 ! 

220 MAT DISP Array33/ ! Trailing "/" means line-feed. 

230 ! 

240 END 

Here are the program's results: 



11 






12 


21 






22 


31 






32 


11 


12 


13 




21 


22 


23 




31 


32 


33 




11 








12 








13 








21 








22 








23 








31 








32 








33 









13 
23 
33 
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The terminator following the array name (semicolon, comma, or slash) is used to specify the 
spacing between elements of the array. 



Table 4-2. Terminators 



Terminator 



Spacing Between Elements 



/ 



Fields — elements will be placed at the beginning of 21 -column 
fields. (This is also the default terminator if another is not 
specified.) 

Compact — elements will have one leading and one trailing 
space. If the number is negative, then the leading space is 
replaced by a minus sign. 

One element per line. 



You can also specify whether an array is to be displayed by rows (default) or by columns. 
Normally, vectors (one-dimensional arrays) are displayed or printed with one element per line. 
If you specify COL before the vector name, however, elements of the vector are displayed or 
printed across a line. Here is an example: 



100 


OPTION BASE 1 


110 


DIM Vector (9) 


120 


! 


130 


DATA 1,2,3,4,5,6,7,8,9 


140 


MAT READ Vector 


150 


! 


160 


MAT DISP Vector; ! 


170 


! 


180 


MAT DISP COL Vector; ! 


190 


I 


200 


END 



One element per line. 



All elements on same line. 



Upon execution of this program, the following is displayed: 

1 
2 
3 
4 
5 
6 
7 
8 
9 
123456789 
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This statement displays Array33 by rows with compact spacing and then by columns with 
compact spacing. 



100 


OPTION BASE 1 




110 


REAL Array33(3,3) ! 3x3 array. 


120 


! 




130 


DATA 11,12,13,21,22,23,31,32,33 


140 


MAT READ Array33 




150 


i 




160 


MAT DISP Array33; ! 


Default (by 


170 


DISP 




180 


! 




190 


MAT DISP ROW Array33; 


! By rows . 


200 


DISP 




210 


! 




220 


MAT DISP COL Array33; 


! By columns . 


230 


DISP 




240 


i 




250 


END 





Here is the program's output: 

11 12 13 
21 22 23 
31 32 33 

11 12 13 
21 22 23 
31 32 33 

11 21 31 

12 22 32 

13 23 33 

If you do not specify either ROW or COL, then the default (ROW) display order is used. If you specify 
ROW before an array name, elements are displayed or printed on each line by rows, beginning 
with the first row (0 or 1, depending on the current OPTION BASE in effect). Each row begins 
on a new line, and the elements in each row are listed in order from the first column to the 
last. More than one line may be required to list the elements in each row, depending on the 
terminator following the array name, the number of elements in each row, the number of digits 
in the values of the elements, and the display's screenwidth or printer's linewidth. 
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If you specify COL before an array name, elements are displayed or printed on each line by 
columns, beginning with the first column ("column-major" order). Each column begins on a new 
line; and the elements in each column are listed in order from the first row to the last. Again, 
more than one line may be required to list the elements in each column; this depends on the 
terminator following the array name, the number of elements in each column, the number of 
digits in the values of the elements, and the printer line width. 

Specifying neither ROW nor COL before an array name has the same effect as specifying ROW. 

If more than one array is specified, a blank line appears between the display or printout of each 
array. 

Using Images 

You can achieve more complete control of the spacing between array elements with the MAT 
DISP USING and MAT PRINT USING statements. 

One form of these statements includes an image string that specifies how array elements are 
displayed or printed. 

MAT DISP USING "5D.D" ; Numbers, 

Another form specifies the line number of an IMAGE statement. 

100 IMAGE 5D.D 

110 MAT DISP USING 100; Numbers, 
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As with the MAT DISP and MAT PRINT statements, specifying COL before the array name causes 
elements to be displayed or printed one column per display (or printer) line: the array elements 
are sent in column-major order, from first row to last row of a column, from the first column to 
the last column. Otherwise, elements are displayed or printed in row-major order. Here is an 
example: 

100 OPTION BASE 1 

110 DIM Array43(4,3) .Vector 10(10) ,Array45 (4, 5) 

120 ! 

130 DATA 126.4,5.4,243.3,364.4,248.2,215.7 

140 DATA 548.9,548.6,18.5,75,10.3,518.1 

150 MAT READ Array43 

160 PRINT "Array43:" 

170 MAT PRINT USING "2X,3D.2D" ; Array43 

180 PRINT 

190 ! 

200 DATA 48,21,94,4,18,44,27,98,72,69 

210 MAT READ VectorlO 

220 IMAGE "VectorlO: **/10(DDD) 

230 MAT PRINT USING 220 ; COL VectorlO 

240 PRINT 

250 ! 

260 DATA 25,23,17,12,77,17,13,11,7,48 

270 DATA 21,18,12,13,64,63,54,40,32,189 

280 MAT READ Array45 

290 PRINT "Array45." 

300 MAT PRINT USING 310 ; Array45 

310 IMAGE 4(2D,X),X,3D/ 

320 ! 

330 END 

This program prints the contents of three arrays using three different implementations of the 
MAT PRINT USING statement. Here are the results. 

Array43 : 

126.40 5.40 243.30 

364.40 248.20 215.70 

548 . 90 548 .60 18 . 50 

75.00 10.30 518.10 

VectorlO: 
48 21 94 4 18 44 27 98 72 69 

Array43 : 

25 23 17 12 77 

17 13 11 7 48 

21 18 12 13 64 

63 54 40 32 189 
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Redimensioning Arrays 

Once an array has been dimensioned, you can reorganize it into a different size by redimensioning 
it. This example dimensions Array4 with 4 elements, and then redimensions it to a working size 
of 3 elements. 

100 OPTION BASE 1 

110 DIM Array4(4) ! 4-element array. 



400 REDIM Array4(3) ! Change working size to 3 elements. 

Subsequent statements affect only the elements included in the new working size. In this example, 
you cannot access the 4th element of the array. Although this 4th element still exists in memory, 
the value of this element cannot be changed until the array is appropriately redimensioned (again). 

The redimensioning subscripts are numeric expressions that specify a new upper bound for 
each dimension; they can be variables, constants, or arithmetic expressions. The number of 
subscripts must be the same as the number specified in the original DIM, REAL, SHORT, or 
INTEGER statement. For example, you cannot redimension a two-dimensional array into a one- 
dimensional array. Furthermore, the total number of elements in the new working size cannot 
exceed the number originally dimensioned. For example, you cannot redimension a 3x5 array 
into a 4x5 array, but you can redimension it into a 5x3 or a 7x2 array. 

This example redimensions Array 2 from a 3x5 array (15 elements) into a 4x2 array (8 elements). 

100 OPTION BASE 1 

110 DIM Array35(3,5) ! 3x5 array (15 elements). 



400 REDIM Array35(4,2) ! 4x2 array (8 elements). 

This statement redimensions Array4 and Array35 to their original sizes. 
REDIM Array4(4) ,Array35(3,5) 

This example redimensions Array29 from a 2x9 array into a 3x6 array. 

100 OPTION BASE 
110 DIM Array29(l,8) 



395 X=2 @ REDIM Array29(X, 10/X) 
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When the array is redimensioned, the values in the array variable in memory are not changed. 
The only difference is that the correspondence between subscript(s) and elements are changed. 
The following example shows how values in an array variable are accessed when an array 
originally declared to be 3x3 is redimensioned into a 2x2 array. 



100 


OPTION BASE 1 




110 


DIM Array33(3,3) 




120 


! 




130 


DATA 11,12,13,21,22, 


,23,31,32,33 


140 


MAT READ Array33 ! 


Reads in "row major 


150 


! 




160 


MAT DISP Array33; ! 


3x3 array. 


170 


DISP 




180 


I 




190 


REDIM Array33(2,2) ! 


! 2x2 array. 


200 


MAT DISP Array33; 




210 


DISP 




220 


! 




230 


REDIM Array33(3,3) ! 


! 3x3 array. 


240 


MAT DISP Array33; 




250 


! 




260 


END 





order . 



The results of running the program look like this: 



11 


12 


13 


21 


22 


23 


31 


32 


33 


11 


12 




13 


21 




11 


12 


13 


21 


22 


23 


31 


32 


33 



The program first dimensions Array33 to be a 3x3 array. The MAT READ statement fills Array33 
with values specified in the DATA statement. The DATA values are placed into the array in "row- 
major" order: all column elements of a row are read, beginning with the lowest-numbered column, 
and then the next higher-numbered row is read, and so forth through the highest-numbered row. 
Note that each element's value corresponds to its subscripts; for instance, Array33(l,l)=ll and 
Array33(2,2)=22. 

The program displays Array33, and then redimensions it to a 2x2 array. The 2x2 array is 
then displayed, and redimensioned back to the original array size and displayed once again. 
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Note that redimensioning an array does not isolate a subarray. In other words, if you redimension 
a 3 X 3 array into a 2 X 2 array, the resulting array is not the 2x2 subarray in the upper left corner 
of the original array. Such operations are covered in the subsequent section called "Copying 
Subarrays." 

REDIM is not the only statement that redimensions an array. The MAT . . . CON , MAT . . . ZER, and 
MAT. . .IDN statements allow you to optionally specify redimensioning subscripts. These state- 
ments assign certain values to the array specified. If redimensioning subscripts are specified, the 
array is redimensioned before the assignments are performed. See the corresponding sections 
later in this chapter for further information. 

Implicit redimensioning may also be performed with statements that specify both a result array 
and an operand array. Here is an example: 

100 OPTION BASE 1 

110 DIM Array22 (2,2), Array33 (3,3) 

120 ! 

130 DISP "Before assigning values from a smaller array." 

140 MAT DISP Array33, ! Will contain all 0's. 

150 DISP DISP 

160 ! 

170 DISP "After assigning values from a smaller array." 

180 MAT Array22=(2) ! Assign '2' to all elements. 

190 MAT Array33=Array22 ! Now assign 2x2 to 3x3 array. 

200 MAT DISP Array33, ! Now show new values. 

210 ! 

220 END 

Here are the results of running the program: 

Before assigning values from a smaller array. 






After assigning values from a smaller array. 
2 2 

2 2 

The program first dimensions two arrays: Array22 is a 2x2 array, while Array33 is a 3x3 
array. 

The contents of Array33 are then displayed. From the three rows of three columns of 0's, you 
can see that it is a 3x3 array. 
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The contents of the smaller Array22 (2x2) are assigned to the larger Array33 (3x3). The result 
of the assignment is that Array33 is first implicitly redimensioned to a 2x2 array, and then the 
contents of elements of Array22 are assigned to corresponding elements of Array33. 

Here is a description of the general case. The result array (such as Array33 above) is redimen- 
sioned to accommodate the elements of the operand array (such as Array22 above) before the 
new values are assigned. The number of rows in the result array will then equal the number of 
rows in the operand array, and the same is true for the number of columns. If the size of the 
result array is greater than that of the operand array, then the result array is first redimensioned 
to match the size of the smaller operand array. Conversely, if the current size of the result array 
is smaller than that of the operand array, then the result array is first redimensioned to match 
the size of the larger operand array. Note, however, that this second case requires that the size 
of the result array (when originally dimensioned) was at least as large as the current size of the 
operand array; if not, an error is reported. 



NOTE 

When an array has been redimensioned — either explicitly or implicitly 
— the array remains redimensioned even when the program that orig- 
inally dimensioned it is run again. The array is not dimensioned back 
to the original size declared in the program's DIM, REAL, SHORT, or IN- 
TEGER statement. If a program is rerun, and it contains an array that 
is redimensioned (either in the program or from the keyboard), then a 
REDIM statement that specifies the original size should be included in the 
program between the DIM , REAL , SHORT, or INTEGER statement and the 
first statement or function that accesses the array or one of its elements. 
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Assigning Values to an Entire Array 

Earlier sections showed examples of assigning values to individual array elements. This section 
describes several methods of assigning values to every element of an array with a single BASIC 
statement. 

Assigning Values From the Keyboard 

The MAT INPUT statement allows you to assign values to elements of a numeric array from the 
keyboard. The MAT INPUT statement is programmable only; it cannot be executed from the 
keyboard. Here is an example: 

100 OPTION BASE 1 

110 DIM Vector(3) ,FirstMatrix(5,4) ,SecondMatrix(2,3) 

120 MAT INPUT Vector, FirstMatrix 

130 RAD X=PI/6 Y=PI/3 

140 MAT INPUT SecondMatrix 

150 ! 

160 MAT PRINT Vector; 

170 MAT PRINT FirstMatrix; 

180 MAT PRINT SecondMatrix; 

190 ! 

200 END 

When the computer prompts you for the first element of Vector: 
Vector(l)? 

Enter all 3 elements of Vector as follows: 



1,2,3 1 Return | 

Since all three elements of Vector have been entered, the program then prompts you to enter 
the first element of the 5x4 array named FirstMatrix. 

FirstMatrix(l.l)? 
Respond to the prompt by entering the first 10 of twenty elements: 



1,2,3,4,5,6,7,8,9,10 | Return | 

All elements are assigned values in order from lowest-numbered column to highest-numbered 
column within a row, beginning with the lowest-numbered row and finishing with the highest- 
numbered row. After you press the carriage return key, the computer displays the name of the 
next element to be assigned a value. In this case, the next prompt requests that you enter the 
eleventh element of FirstMatrix. 

FirstMatrix(3,3)? 



Numeric Computation 4-37 



Respond to this prompt by entering the remaining 10 elements as follows: 



11,12,13,14,15,16,17,18,19,20 | Return | 

The next request that you enter the first element of the 2x3 array named SecondMatrix. 
SecondMatrix(l , 1) 

Values can be entered as numbers, as numeric variables, or as numeric expressions. Input into 
the array continues until all elements have been assigned values. If an array becomes full in the 
middle of an input line, then the remaining elements on the line are ignored. 

You can also enter expressions that contain variables and system-resident functions. Note that 
the values assigned to the variables and the values computed for the variable functions are 
entered into the corresponding elements. 

Enter the following for SecondMatrix(l,l): 



X,SIN(X),1-C0S(2*X) [ Return 1 

The final prompt given is: 
SecondMatrix(2,l) 

Now enter the remaining 3 elements into array SecondMatrix. 



Y,C0S(Y) ,1-SIN(2*Y) | Return 1 

The execution of your program is now complete. Here is what the program prints (assuming 
that you entered the values shown in preceding paragraphs): 

1 
2 
3 

12 3 4 
5 6 7 8 

9 10 11 12 

13 14 15 16 
17 18 19 20 
.523598775598299 .5 .5 
1.0471975511966 .5 .133974596215561 

This program's purpose was to show you how the MAT INPUT statement prompts you to enter all 
values into an array. It also showed how several elements could be entered at one time. However, 
if you prefer entering elements individually, then you can enter one numeric expression at a time, 
pressing the carriage-return key after each one. 
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Assigning Values from a DATA Statement 

Like the READ statement, the MAT READ statement can be used in conjunction with one or more 
DATA statements. When MAT READ is executed, elements of the array are assigned values from 
the list of numbers in a DATA statement. Array elements are assigned values in row-major order, 
just as they are in the MAT INPUT statement. The items in a DATA statement that correspond to 
numeric array elements must be valid numeric values, not string values. 

The MAT READ statement is programmable only; it cannot be executed from the keyboard. The 
following program is an example of using this statement. 

100 OPTION BASE 1 

110 INTEGER Numbers (2, 5) 

120 DIM Titlel$[ll] ,Title2$ [12] 

130 ! 

140 ! Years 

150 DATA 1920,1930,1940,1950,1960 

160 ! 

170 ! Numbers of U.S. drivers. 

180 DATA 14,38,48,62,87 

190 DATA "Millions of "."U.S. Drivers" 

200 ! 

210 MAT PRINT Numbers 

220 READ Titlel$,Title2$ 

230 ! 

240 PRINT Titlel$ 

250 PRINT Title2$ 

260 PRINT " " 

270 FOR Line=l TO 5 

280 PRINT Numbers (1, Line) ; Numbers (2, Line) 

290 NEXT Line 

300 ! 

310 END 

The results of executing this program are as follows: 

Millions of 
U.S. Drivers 



1920 14 

1930 38 

1940 48 

1950 62 

1960 87 
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Assigning the Same Value to Every Element 

The MAT statement also allows you to assign the value of a numeric expression to all elements 
of an array. For instance, this statement assigns the value 30.48 to all elements of array X. 

MAT X = (30.48) 

This statement assigns the value of the variable M to all elements of array Y. 
MAT Y = (M) 

This statement assigns the result of the expression 2*PI*Raduis~2 to all elements of array Z. 
MAT Z = (2*PI*Radius"2) 

Constant and Zero Matrices 

The MAT . . . CON statement assigns the value 1 to all elements of an array. Here is an example: 
MAT Array 1 = CON 

Every element in the array will now contain a value of 1. 

You can also use this statement to redimension an array: 
MAT Array3 = CON (2, 2) 

Assuming OPTION BASE 1, if array A was originally a 3x3 array, then it would be redimensioned 
to a 2x2 array. All elements of the redimensioned array would then be assigned a value of 1. 

The MAT. . .ZER statement assigns the value to all elements of the result array. An array in 
which all elements are zero is called a zero matrix. Likewise, a vector of which all elements are 
zero is called a zero vector. Here is an example: 

MAT Array3 = ZER 

You can also redimension the array: 
MAT A = ZER (5, 2) 
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Assuming OPTION BASE 1, if array A was originally a 5x5 array, then it would be redimensioned 
to a 5x2 array. All elements of the redimensioned array would then be assigned a value of 0. 

Here is another example. 



100 


OPTION BASE 1 


110 


DIM Array43(4,3) 


120 


! 


130 


MAT Array43=ZER ! 


140 


MAT DISP Array43; 


150 


DISP 


160 


i 


170 


MAT Array43=C0N(3,2) 


180 


MAT DISP Array43; 


190 


DISP 


200 


! 


210 


REDIM Array43(4,3) ! 


220 


MAT DISP Array43; 


230 


! 


240 


END 



Zero 4x3 array. 



Redim, and assign 1 to first 6 elements. 



Restore 4x3 array subscripts . 



This program displays the following results: 







































1 


1 




1 


1 




1 


1 




1 


1 


1 


1 


1 


1 
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The Identity Matrix 

An identity matrix is created using the MAT . . . IDN statement. MAT . . . IDN assigns the value 1 to 
all diagonal elements of the result matrix and assigns the value to all other elements. (Diagonal 
elements are those for which the row subscript is equal to the column subscript.) A matrix 
created using the MAT . . . IDN statement is also called a unit matrix. An example program using 
MAT. . .IDN is as follows: 

100 OPTION BASE 1 

110 DIM Array33(3,3) ,Array55(5,5) 

120 ! 

130 MAT Array33=IDN 

140 MAT DISP Array33; 

150 DISP 

160 ! 

170 MAT Array55=IDN(4,4) 

180 MAT DISP Array55; 

190 ! 

200 END 

Execution of the above program produces the following result: 

10 
10 
1 

10 
10 
10 
1 

This program dimensions Array33 to be a 3x3 array and dimensions Array55 to be a 5x5 
array. It also makes them both identify matrices and displays them. Note that Array55 is 
redimensioned to a 4x4 identity matrix by specifying the corresponding subscript values in the 
MAT. . .IDN statement. Note also, however, that you cannot redimension arrays to be larger than 
the dimensions specified in the declaration statement that originally specified the array's size. 



NOTE 

The array specified in a MAT . . . IDN statement must be a square matrix; 
that is, it must have two dimensions, and the number of rows must be 
the same as the number of columns. 
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Copying Subarrays 

An earlier section discussed copying the contents of an entire array into another array. For 
instance, this statement is used to copy every element of Array33 into Array55. 

MAT Array55=Array33 

If Array33 and Array55 are of the same size, then each element of Array33 is copied into the 
corresponding element of Array55. However, if Array33 is a 3x3 array and Array55 is a 5x5 
array, then this statement redimensions Array55 into a 3x3 array and then copies the nine 
elements of Array33 into corresponding elements of Array55. 

With Technical BASIC, you can also copy a subset of an array (herein called a "subarray") into 
another array. Here is a simple example: 

100 OPTION BASE 1 

1 10 DIM Array55 (5,5), Array33 (3 , 3) 

120 ! 

130 MAT Array55=(5) ! Fill with all 5's. 

140 MAT DISP Array55; 

150 DISP 

160 ! 

170 MAT Array33=(3) ! Fill with all 3's. 

180 MAT DISP Array33; 

190 DISP 

200 ! 

210 MAT Array55(2:4,2:4)=Array33 ! Put Array33 into subarray. 

220 MAT DISP Array55; 

230 ! 

240 END 

Here are the program's results: 



5 5 5 5 5 

5 5 5 5 5 

5 5 5 5 5 

5 5 5 5 5 

5 5 5 5 5 

3 3 3 

3 3 3 

3 3 3 

5 5 5 5 5 

5 3 3 3 5 

5 3 3 3 5 

5 3 3 3 5 

5 5 5 5 5 
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The example copies all of Array33 into columns 2 through 4 of rows 2 through 4 of Array55. 
The rest of Array55 is not changed, and the array is not redimensioned. 

In general, you can specify both starting and ending row and starting and ending column for 
both the operand (Array33 above) and result (Array55 above). Subsequent examples explain 
this more clearly. 

Several Examples of Copying Subarrays 

The following examples show several usages of the MAT statement in copying subarrays. For 
these examples, assume that OPTION BASE 1 is in effect and that all values in the 5x5 array 
named Result55 are set to zero before each statement is executed. The values shown for the 
Result arrays are the values that it will contain after the corresponding MAT statement has been 
executed. 

This statement copies the value from each element of Operand55 into the corresponding element 
of Result55. 

MAT Result55 = 0perand55 

0perand55 Result55 

11 12 13 14 15 11 12 13 14 15 

21 22 23 24 25 21 22 23 24 25 

31 32 33 34 35 31 32 33 34 35 

41 42 43 44 45 41 42 43 44 45 

51 52 53 54 55 51 52 53 54 55 

This statement redimensions Result55 to a 3x3 matrix (since no subscripts were specified for 
the Result55 array); then it copies the values from columns 1 through 3 of rows 1 through 3 of 
Operand55 into the redimensioned Result55. 

MAT Result55 = 0perand55(l :3, 1 :3) 



0perand55 


Result55 


11 12 13 14 15 


11 12 13 


21 22 23 24 25 


21 22 23 


31 32 33 34 35 


31 32 33 


41 42 43 44 45 




51 52 53 54 55 
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This statement copies the third element of Vector into the element in row 3 of column 2 of 
Result55. 

MAT Result55(3,2) = Vector (3) 



Vector 

1 
2 
3 
4 
5 





Result55 

























3 
























This statement copies the values from row 1 columns 2 through 4 of Operand55 into row 3 
columns 1 through 3 of Result55. 

MAT Result55(3,l:3) = 0perand55(l ,2:4) 



0perand55 




Result55 




11 12 13 14 15 











21 22 23 24 25 











31 32 33 34 35 


12 


13 14 





41 42 43 44 45 











51 52 53 54 55 












This statement copies the values from rows 4 and 5 of column 1 of Operand55 into rows 2 and 
3 of column 5 of Result55. 

MAT Result55(2:3,5) = 0perand55(4:5, 1) 



0perand55 


Result55 


11 12 13 14 15 





21 22 23 24 25 


41 


31 32 33 34 35 


51 


41 42 43 44 45 





51 52 53 54 55 
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This statement copies the entire Vector into the entire third row of Result55. 
MAT Result55(3,) = Vector 

Vector 

1 
2 
3 

4 
5 

This statement copies the entire second column of Operand55 into Vector. 
MAT Vector = 0perand55( ,2) 





Result55 






















1 


2 3 4 


5 





















0perand55 




Vect« 


11 12 13 14 


15 


12 


21 22 23 24 


25 


22 


31 32 33 34 


35 


32 


41 42 43 44 


45 


42 


51 52 53 54 


55 


52 



This statement copies the values from rows 1 and 2 of columns 2 through 5 of Operand55 into 
rows 2 and 3 of columns 1 through 4 of Result55. 

MAT Result55(2:3,l:4) = 0perand55(l :2,2:5) 



0perand55 




Result55 




11 12 13 14 15 











21 22 23 24 25 


12 


13 14 15 





31 32 33 34 35 


22 


23 24 25 





41 42 43 44 45 











51 52 53 54 55 












This statement redimensions Result55 into a 2x3 matrix, and copies the values from rows 1 
and 2 of columns 3 through 5 of Operand55 into Result55. 

MAT Result55 = 0perand55(l:2 ,3:5) 

0perand55 Result55 

11 12 13 14 15 13 14 15 

21 22 23 24 25 23 24 25 

31 32 33 34 35 

41 42 43 44 45 

51 52 53 54 55 
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Summary of General Rules 

• The array elements are always copied and assigned in row-major order — from the first 
column to the last column of each row, beginning with the first row and proceeding through 
the last row. 

• If all elements of the result array are to be assigned values, then do not specify row 
numbers or column numbers in the result array. 

• If all elements of the operand array are to be copied into the result array, then do not 
specify row numbers or column numbers in the operand array. 

• If row and/or column numbers are specified, they must be enclosed in parentheses and 
separated by a comma. 

• If no row or column numbers are specified after the result array, then it is redimensioned 
(if necessary) before values are assigned to it. If row or column numbers are specified after 
the result array, then values are assigned to the corresponding elements and the array is 
not redimensioned. 

• If the array is a vector, then specify only the row number(s). 

• If only one row is to be copied or assigned values, then you need only specify that one 
row number; if more than one row is to be copied or assigned values, then specify the first 
row number and the last row number, separated by a colon. Similarly, if only one column 
is to be copied or assigned values, then you need only specify that one column number; 
if more than one column is to be copied or assigned values, then specify the first column 
number and the last column number, separated by a colon. 

• If entire row(s) are to be copied or assigned values, then you may omit the column numbers 
but include a comma after the row number(s). Similarly, if entire column(s) are to be copied 
or assigned values, then you may omit the row numbers but include a comma before the 
column number (s). 

• Unless either the operand array or the result array is a vector, the number of rows 
specified after the result array must be the same as the number of rows to be copied from 
the operand array. The number of columns specified after the result array must be the 
same as the number of columns to be copied from the operand array. 

• Unless the operand array is a vector, a column from the operand array cannot be copied, 
using just one statement, into a row in the result array. Similarly, unless the result array is 
a vector, a row from the operand array cannot be copied, using just one statement, into a 
column of the result array. These types of copy operations can, however, be made using 
two statements, as shown in the next example. 
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In this example, row 1 of Array33 is copied into column 3 of array Result55, then column 3 of 
Array33 is copied into row 2 of array Result55. 



100 
110 
120 
130 
140 
150 
160 
170 
180 
190 
200 
210 
220 
230 
240 
250 
260 
270 
280 
290 



OPTION BASE 1 

DIM 0perand33 (3,3), Result33 (3,3), Vector3 (3) 



DATA 1,2,3,4,5,6,7,8,9 
MAT READ 0perand33 ! 
MAT DISP 0perand33; ! 
DISP 
! 

MAT Result33=ZER ! 

MAT Vector3=0perand33(l.) ! 

MAT Result33(,3)=Vector3 ! 

MAT DISP Result33; 

DISP 

! 

MAT Result33=ZER ! 

MAT Vector3=0perand33(,3) ! 

MAT Result33(2,)=Vector3 ! 

MAT DISP Result33; 

! 

END 



Fill 3x3 matrix. 
Show contents. 



Fill result with O's. 
Copy row 1 into vector. 
Copy vector into column 3 . 



Fill result with O's. 
Copy column 3 into vector , 
Copy vector into row 2 . 



Here are the results obtained from the program: 



12 3 
4 5 6 
7 8 9 



The first matrix displayed is Operand33. The next matrix displayed is matrix Result33, with 
column 3 containing values from row 1 of matrix Operand33. The final matrix displayed is 
Result33 again, but this time with row 2 containing values from column 3 of Operand33. 



The row and column number(s) can be specified not only as constants, like those in the preceding 
examples, but also as variables or expressions. Here is an example: 



245 Column=2 

250 MAT Vector3=0perand33(, Column) ! 

255 BottomRow=3 

260 MAT Result33(BottomRow-2,)=Vector3 ! Copy vector into row 1. 



Copy column 2 into vector. 
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The first row (or column) number specified is usually less than the second row (or column) 
number. However, if the first row number is greater than the second (or if the first column 
number is greater than the second), then elements will be copied or assigned values in reverse 
order 1 . The first row or column number actually copied or assigned values is one less than the 
specified beginning row/column number. Similarly, the last row or column copied or assigned 
values is one greater than the specified last row/column number. For instance, the following 
statement copies rows 4 through 1 of the operand into rows 1 through 4 of the result array. 

180 MAT Result(l:4,l:4)=0perand(5:0,l:4) 

Here is an example program containing this statement: 

100 OPTION BASE 1 

110 DIM Result (4, 4) .Operand (4, 4) 

120 ! 

130 DATA 1,1,1,1,2,2,2,2,3,3,3,3,4,4,4,4 

140 MAT READ Operand 

150 MAT DISP Operand; 

160 DISP 

170 ! 

180 MAT Result(l:4,l:4)=0perand(5:0,l:4) ! Copy Operand rows 4 thru 1 

190 ! into Result rows 1 thru 4 . 

200 MAT DISP Result ; 

210 ! 

220 END 

Here is the program's output: 

1111 

2 2 2 2 

3 3 3 3 

4 4 4 4 

4 4 4 4 
3 3 3 3 
2 2 2 2 

1111 

The program reverses rows 1 through 4 of the Operand array as it copies them into the Result 
array. 



An important special case occurs when the first row number specified is just one greater than the second row number, or when the first 
column number specified is just one greater than the second column number. This subject will be discussed in the subsequent section 
called "A Special Case: Empty Arrays." 
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A Special Case: Empty Arrays 

Here is the special case mentioned earlier: When the first row specified is just one greater than 
the second row, and with the corresponding case for columns, then no elements will be copied or 
assigned values. Furthermore, if no row or column numbers are specified after the result array 
(and OPTION BASE 1 is in effect), then the result array is redimensioned to have zero rows or 
zero columns 1 . The value of these features will be more apparent after we discuss this special 
case a bit more. 

Examples of this special case are contained in this program: 

100 OPTION BASE 1 

110 DIM Operand (4 ,4) .Result (4, 4) 

120 MAT Operand=CON ! Assign all l's. 

130 DISP 

140 MAT DISP Operand; 

150 DISP 

160 K=l 

170 MAT Result=0perand(l:K-l,2) 

180 DISP "After copying Operand rows '1:0'." 

190 MAT DISP Result; 

200 DISP 

210 MAT Result=0perand(l:4,l:K-l) 

220 DISP "After copying Operand columns '1:0'." 

230 MAT DISP Result; 

240 ! 

250 END 

The program yields this output: 

1111 
1111 
1111 
1111 

After copying Operand rows '1:0'. 

After copying Operand columns '1:0'. 

The display of Operand shows that it is indeed a constant matrix. The first display of array 
Result showed nothing because it was redimensioned to a 0x2 array, which is by definition an 
"empty" array. The second display of array Result was the same as the first, except that the 
number of columns is and the array is redimensioned to a 4x0 empty array. Empty arrays 
should not be confused with zero arrays, which contain all O's. If you should display or print 
an empty array, there will be no output since there are no elements in the array (according to 
current dimensions). 



If OPTION BASE is in effect, the result array is not redimensioned, and a DIM SIZE error message is reported. 

4-50 Numeric Computation 



Empty arrays can be specified in subsequent statements and functions with meaningful results; the 
usual rules of redimensioning and row/column matching apply (in statements with two operand 
arrays). The following situations are of particular interest: 

• Statements specifying only one operand array will, if that array is empty, redimension the 
destination array to be empty. For example, if the Operand array has been redimensioned 
to a 0x3 array, then this statement redimensions the Result array to 0x3: 

MAT Result = Operand 

• If both operand arrays are empty, then performing a matrix multiplication 1 can yield a 
result array that is not empty. However, in such cases the statement assigns the value 
to all elements of the destination array, regardless of the current values in the operand 
arrays. 

For example, if matrix Operandi has been redimensioned to be 3x0, and matrix Operand2 has 
been redimensioned to be 0x1, then this statement: 

MAT Result = 0perandl*0perand2 

redimensions matrix Result to 3x1, since 3x0*0x1=3x1 according to the rules of matrix 
multiplication. The Result array is not empty, since neither its number of rows nor number 
of columns is zero. However, it is a zero matrix, since the value has been assigned to 
all (three) elements. 

The fact that no elements are copied or assigned values when the first row or column number is 
just one greater than the second, plus the characteristics previously described above for resulting 
empty arrays, simplifies programs that do certain matrix manipulations. 



Matrix multiplication is discussed in a subsequent section. 
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Scalar Arithmetic Array Operations 

You can perform scalar arithmetic operations with a scalar numeric expression (such as a constant, 
variable, or expression) and each element of an operand array. For example, you could add the 
constant 4 to each element of an array: 

MAT ArrayX=(4)+ArrayX 
The resulting values are assigned to the corresponding elements of the result array (ArrayX). 

The scalar arithmetic operations that you can perform with MAT keywords are as follows: 

• Addition (+) 

• Subtraction (— ) 

• Scalar multiplication (.), also known as the inner or dot product 

• Division (/) 

The following program makes Array44 an identity matrix. (An identity matrix is a square matrix 
which contains all ones in a diagonal which begins at its first element and moves down to its last 
element; the remainder of the elements in the identity array contain zeros.) The program then 
multiplies each element of that array by the scalar 2. 



100 


OPTION BASE 1 


110 


DIM Array44(4,4) 


120 


I 


130 


MAT Array44=IDN 


140 


MAT PRINT Array44; 


150 


PRINT 


160 


! 


170 


MAT Array44= (2) *Array44 


180 


MAT PRINT Array44; 


190 


! 


200 


END 



The result of executing the above program looks like this: 



10 

10 

10 

1 

2 

2 

2 

2 
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If you need to change the signs of all elements in a matrix, you can do so inserting the following 
statement in the preceding program: 

145 MAT Array44 = -Array44 

The array now contains these values: 

-2000 
0-200 
0-20 
0-2 

You can also perform these scalar arithmetic operations with corresponding elements of two 
operand arrays: addition, subtraction, (dot-product) multiplication, and division. For instance, 
this statement calculates the squares of the elements in an array: 

MAT Array33=Array33 . Array33 

The statement multiplies Array33(l,l) by Array33(l,l) and places the result in Array33(l,l). 
It does the same for each corresponding element of the operand arrays. Multiplication of 
corresponding elements is known as the dot product or inner product of the arrays; the operator 
for this type of operation is a period (.J 1 . Note that the two operand arrays must have the same 
number of elements in each dimension. 

The result of two scalar multiplications can be added in one statement. An example is given 
below: 

100 OPTION BASE 1 

110 DIM Arrayl(2,4),Array2(2,4) 

120 ! 

130 DATA 12,52,76,33,81,70,72,14 

140 MAT READ Arrayl 

150 ! 

160 MAT Array2=(50) Array2(l ,2) ,Array2(2, 1)=0 

170 ! 

180 DEG ! Use degrees mode (for angular functions) . 

190 MAT Arrayl=(0.7)*Arrayl+(0.3*SIN(60))*Array2 

200 MAT DISP USING "2X,DD.D" ; Arrayl 

210 ! 

220 END 



The asterisk (*) is used to denote matrix multiplication, which is a different kind of operation and is described in the subsequent section 
called "Matrix Multiplication." 
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The results of executing this program are as follows: 



21.4 36.4 66.2 36.1 
56.7 62.0 63.4 22.8 

Subtracting the results of two scalar multiplications can be accomplished in one statement by 
changing the sign of the second scalar. In the preceding example, change the statement 190 to: 

190 MAT Arrayl=(0.7)*Arrayl+(-0.3*SIN(60))*Array2 

Here are the modified program's results: 

-4.6 36.4 40.2 10.1 
56.7 36.0 37.4 -3.2 

However, multiplying or dividing the results of two scalar multiplications cannot be performed 
with one statement. 

Summing Rows and Columns 

Technical BASIC provides MAT capabilities that allow you to compute the sum of elements in 
rows and columns of arrays. 

• MAT. . .RSUM calculates the sum of elements in a row. 

• MAT. . .CSUM calculates the sum of elements in a column. 

Usages of MAT. . .RSUM and MAT. . .CSUM are shown in the following example. 

Here is the Whackit Racket Company's monthly forecast data table. It is organized into sales 
regions (East, Midwest, and West) and racket model (WR01, WR02, and WR03). 

Table 4-3. Monthly Sales Forecast (Thousands of Units) 







Model 




Sales Region 


WR01 


WR02 WR03 


WR04 


East 


25 


23 17 


12 


Midwest 


17 


13 11 


7 


West 


21 


18 12 


13 



The program calculates and prints the total forecast for all racket models — one forecast by 
region, and another by racket model. Since each row contains the forecasts for all models in 
a region, the total forecast for all models in each region can be found using the MAT. . .RSUM 
statement. Likewise, since each column contains the forecasts for one model in all regions, the 
total forecast for each model in all regions can be found using the MAT. . .CSUM statement. 
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100 OPTION BASE 1 

110 DIM Forecasts (3, 4) ,RegionSums(3) ,ModelSums(l ,4) 

120 ! Forecast for the Eastern region. 

130 DATA 25,23,17,12 

140 ! Midwest region. 

150 DATA 17,13,11,7 

160 ! West region. 

170 DATA 21,18,12,13 

180 MAT READ Forecasts 

190 ! 

200 PRINT "Forecasts:" 

210 PRINT " " 

220 MAT PRINT Forecasts; 

230 PRINT 

240 MAT RegionSums=RSUM (Forecasts) ! Row sums to vector. 

250 PRINT "Forecasts by Region:" 

260 PRINT " " 

270 MAT PRINT RegionSums ; 

280 PRINT 

290 PRINT "Forecasts by Model:" 

300 PRINT " " 

310 MAT ModelSums=CSUM (Forecasts) ! Columns sums to matrix. 

320 MAT PRINT ModelSums; 

330 ! 

340 END 

The results displayed after program execution are: 
Forecasts : 



25 23 17 12 
17 13 11 7 
21 18 12 13 

Forecasts by Region: 

77 

48 
64 

Forecasts by Model: 

63 54 40 32 

The first matrix displayed is the monthly sales forecast (in thousands of units); the rows corre- 
spond to regions, and the columns correspond to racket models. The second matrix has in its 
rows the total sales for the East, Midwest, and West regions, respectively. Finally the last matrix 
has in its columns the total sales of models WR01, WR02, WR03, and WR04, respectively. 
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General Rules 

Here are the rules that govern this type of operation: 

• MAT. . .RSUM adds the values of the elements in each row of the operand array, and then 
assigns the sum to the corresponding element of the result array (a vector or single-column 
matrix). If the result array is a vector, it is first redimensioned (if necessary) to have as 
many elements as the number of rows as the operand array. If the result array is a matrix, 
it is first redimensioned (if necessary) to have one column and as many rows as in the 
operand array. 

• Likewise, MAT. . .CSUM adds the values of the elements in each column of the operand 
array, and then assigns the sum to the corresponding element of the result array (a vector 
or single-row matrix). If the result array is a vector, it is first redimensioned (if necessary) 
to have as many elements as the number of columns as the operand array. If the result 
array is a matrix, it is first redimensioned (if necessary) to have one row and as many 
columns as in the operand array. 

Array Transpose 

The MAT . . . TRN statement computes the transpose of the operand array — interchanges the rows 
and columns of the array — and places the values in the result array. The following program 
shows how this statement can be used within a program: 

100 OPTION BASE 1 

110 DIM Array23(2,3) ,Array55(5,5) 

120 DATA 1,2,3,4,5,6 

130 MAT READ Array23 

140 MAT PRINT Array23; 

150 PRINT 

160 MAT Array23=TRN(Array23) ! Redira, then transpose. 

170 MAT PRINT Array23; 

180 PRINT 

190 MAT Array55=TRN(Array23) ! Redim, then transpose. 

200 MAT PRINT Array55; 

210 END 
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Here is the program's output: 



The first matrix displayed is the original Array23 — a 2x3 matrix. The transpose of Array23 
is then calculated, after which the Array23 variable is redimensioned (to a 3x2 matrix) and then 
and assigned the transposed Array23; the second matrix shown above is the result. Next, the 
transpose of Array23 is computed, then Array55 is redimensioned from a 5x5 matrix to a 2x3 
matrix, and is then assigned the values of the transposed matrix Array23. 

Matrix Multiplication 

The MAT statement can be used to calculate the (outer) product of two arrays. The value 
of each element of the destination array is determined according to the usual rules of matrix 
multiplication. Here is an example: 



i * B = Result 










all al2 


* 


bll 


bl2 


= 


all*bll + al2*b21 


all*bl2 + al2*b22 


a21 a22 




b21 


b22 




a21*bll + a22*b21 


a21*bl2 + a22*b22 



The number of columns in the first operand array (A) must be the same as the number of rows 
in the second operand array (B). The Result array has the same number of rows as the first 
operand array and the same number of columns as the second operand array. Either (but not 
both) of the operand arrays can be vectors. 
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An Example 

Here is an example program that performs the multiplication: 



100 


OPTION BASE 1 




110 


DIM Array23 (2,3), Array32 (3,2), Array22 (2 , 2) 


120 


DATA 1,2,3,4,5,6 




130 


MAT READ Array23 ! 


Fill 2x3 matrix. 


140 


MAT DISP Array23; 




150 


DISP 




160 


DATA 1,4,2,5,3,6 




170 


MAT READ Array32 ! 


Fill 3x2 matrix. 


180 


MAT DISP Array32; 




190 


DISP 




200 


MAT Array22=Array23*Array32 ! Multiply. 


210 


MAT DISP Array22; 


! Result is a 2x2 matrix 


220 


END 





Here are the program's results: 

12 3 
4 5 6 

1 4 

2 5 

3 6 

14 32 
32 77 

The first array displayed is the first operand. The second array is the second operand. The 
third array is the product of matrix multiplication on the two operands. 

Another Example 

The following problem illustrates the use of matrix multiplication. The Whackit Racket Company 
is considering raising the prices on each of its four models: WR01, WR02, WR03, and WR04. 
The sales manager wants a program that uses the data in the following table to calculate and 
print a matrix that shows the total income (in thousands of dollars) in each of the three sales 
regions at the old and at the new prices. (The price increase is not expected to affect the number 
of units sold.) 
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Table 4-4. Monthly Sales Forecast (Thousands of Units) 







Model 




Sales Region 


WR01 


WR02 WR03 


WR04 


East 


25 


23 


17 


12 


Midwest 


17 


13 


11 


7 


West 


21 


18 


12 


13 



Table 4-5. Price (Per Unit) 



Model 


Old 


New 


WR01 


$10 


$15 


WR02 


$20 


$27 


WR03 


$35 


$50 


WR04 


$60 


$80 



In each sales region, the total income (either at the old or at the new prices) can be determined 
by multiplying the quantity of each model by the price of each model, then adding the results. 
Applying this process to the data in the forecast and price tables above, multiply each entry in a 
row of the forecast table by the corresponding entry in a column of the price table, and then add 
the results. The sum could be entered into the same row and column of another table, in which 
each row shows the total income in a sales region and each column shows the total income at 
the old or at the new prices. 

Since all this is just what happens in matrix multiplication, these calculations can be done 
compactly with the matrix multiplication Incomes=Forecasts*Prices, in which: 

• The Forecasts matrix contains the sales forecasts (in thousands of units). The rows corre- 
spond to the three sales regions, and the four columns correspond to the four models. 

• The Prices matrix contains the prices (per unit) of each model. The four rows correspond 
to the four models, and the two columns correspond to the two price lists (old and new). 

• The Incomes matrix will contain the total income in each sales region at the old and at 
the new prices. The three rows will correspond to the three sales regions, and the two 
columns will correspond to the two price lists. 
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100 OPTION BASE 1 

110 DIM Forecasts (3 ,4) ,Prices(4,2) ,Incomes(3,2) 

120 ! Sales for East region. 

130 DATA 25,23,17,12 

140 ! Sales for Midwest region. 

150 DATA 17,13,11,7 

160 ! Sales for West region. 

170 DATA 21,18,12,13 

180 ! Prices. 

190 DATA 10,15,20,27,35,50,60,80 

200 MAT READ Forecasts, Prices 

210 ! 

220 MAT Incomes=Forecasts*Prices 

230 PRINT 

240 PRINT " Old New" 

250 PRINT "Income Income" 

260 PRINT " (k$) (k$)" 

270 PRINT " " 

280 IMAGE X,DC3D,4X,DC3D 

290 MAT PRINT USING 280 ; Incomes 

300 END 

Executing the program produces this result: 

Old New 

Income Income 

(k$) (k$) 



2,025 2,806 

1,235 1,716 

1,770 2,441 

The first row shows incomes from the East region. The second row shows incomes from the 
Midwest region. The third row shows incomes from the West region. 

Transposing before Multiplying 

If you want to multiply two matrices, but the dimensions need to be transposed, you can multiply 
the transpose of one array by the other array. The following problem helps illustrate this usage. 

Assume the manufacturing capacity of the Whackit Racket Company is limited this quarter; it 
can produce only a percentage of the rackets demanded. The table below shows the percentage 
that can be supplied to each region in the next two months. Using the forecast data in the table 
of the preceding problem, calculate and print a matrix showing how many of each racket model 
will be produced each month. 
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Table 4-6. Production Quota (Percentage) 



Sales Region 


June 


July 


East 

Midwest 

West 


80 
75 
85 


90 
85 
95 



The quantity of each racket model that will be produced (during either month) can be determined 
by multiplying the quantity of each model by the percentage for that model, and then adding 
the results. As in the preceding example, these calculations can be performed easily with a 
matrix multiplication of elements in the sales forecast table by elements in the production quota 
table. To do so, however, requires that the multiplication use the transpose of either the matrix 
containing the forecasts or the matrix containing the quotas. The following program multiplies 
the transpose of the matrix containing the forecasts by a matrix containing the quotas. 

100 OPTION BASE 1 

110 DIM Forecasts (3, 4) .Quotas (3, 2) .Units (4, 2) 

120 ! Sales for East region. 

130 DATA 25,23.17.12 

140 ! Sales for Midwest region. 

150 DATA 17.13,11,7 

160 ! Sales for West region. 

170 DATA 21,18,12.13 

180 ! Production quotas . 

190 DATA 80,90,75.85,85,95 

200 MAT READ Forecasts, Quotas 

210 ! 

220 MAT Quotas=(0.01)*Quotas ! Converts percentages to decimal values. 

230 MAT Units=TRN (Forecasts) *Quotas 

240 PRINT 

250 PRINT " June July" 

260 PRINT "(k-Units) (k-Units) " 

270 PRINT " " 

280 IMAGE 2X.2D.D.7X.2D.D 

290 MAT PRINT USING 230 ; Units 

300 END 

The results from executing this program are shown below: 



June 
(k-Units) 


July 
(k-Units) 


50.6 
43.5 
32.0 
25.9 


56.9 
48.8 
36.0 
29.1 
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Vector Cross Product 

The MAT. . .CROSS statement calculates the vector cross product (or vector product) of two 3- 
element vectors. Mathematically, the cross product of two vectors is expressed as CrossProd = 
Vector3axVector3b. Each of the arrays named in the MAT. . .CROSS statement must be vectors; 
that is, they must have only one dimension. Arrays dimensioned like Matrix(3,l) are not allowed 
because they are two dimensional. 

The following problem illustrates the use of MAT. . .CROSS. A leaning tree has a guyed wire 
connecting it to the corner of a house as shown in the picture. Calculate the moment of the 
force exerted by the guy wire about the base of the tree for a tension in the wire of 960 pounds. 




Figure 4-1. Moment Calculation 

To calculate the moment, use this formula: 
Moment = Radius X Force 

in which: 

• Radius is the position vector of the guy wire point (on the tree) with respect to the base 
of the tree. 

• Force is the 960-pound force vector exerted by the guy wire. 
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Before making the calculation, you will need to resolve the vectors Radius and Force into their 
components in the x, y, and z directions. 

You can determine the components of Radius by looking at the drawing. They are as follows: 

Radius(x) = 5 
Radius(y) = 14 
Radius(z) = 2 

You will need to calculate the Force vector. Since you know that the 960-pound force is exerted 
in the direction of the Guy vector, the x, y, and z components of Force and Guy are proportional. 

Force(x) Force(y) Force(z) | Force | 



Guy(x) Guy(y) Guy(z) |Guy| 

The unknowns in this equation are the x, y, and z components of Force; you already know its 
magnitude, and you can determine the components of Guy and its magnitude. 

The components of Guy, from the illustration, are as follows: 

Guy(x) = -9 - 5 = -14 
Guy(y) = 10 - 14 = -4 
Guy(z) = -4 - 2 = -6 

The magnitude of Guy is equal to the square root of the sum of the squares of each component. 
Here is the equation: 

MagGuy = SQR( Guy(xf2 + Guy(y)~2 + Guy(z)~2 ) 

The program makes this calculation in line 200 below. 

You can now calculate each component of Force by multiplying the corresponding component 
of Guy by the ratio of the magnitude of Force to the magnitude of Guy. 

| | Force | | 
Force(x) =Guy(x) * | |G uy | | 

The program performs this calculation in statement 230. 
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The components of Moment (in lb-ft) are determined by the following program: 

100 OPTION BASE 1 

110 DIM Radius(3) ,Force(3),Guy(3),Moment(3) 

120 ! 

130 ! Components of Radius. 

140 DATA 5,14,2 

150 ! Components of Guy. 

160 DATA -14,-4,-6 

170 MAT READ Radius, Guy 

180 ! 

190 ! Calculate magnitude of Guy. 

200 MagGuy=SQR(Guy(l)~2+Guy(2)~2+Guy(3)~2) 

210 ! 

220 ! Calculate components of Force vector. 

230 MAT Force=(960/MagGuy)*Guy 

240 ! 

250 ! Calculate components of Moment. 

260 MAT Moment=CROSS (Radius, Force) 

270 MAT PRINT USING "5D.DD" ; Moment 

280 ! 

290 END 

The components of Moment are as follows: 

-4632 . 96 

121.92 

10728.97 

The x-component is printed first, then the y-component, and finally the z-component. 

Inverting a Matrix 

The MAT . . . INV statement finds the inverse of the operand matrix. The inverse of a matrix is 
the matrix that, when multiplied by the original matrix, results in an identity matrix. The main 
restriction on the operand matrix is that it must be square — that is, the number of rows must 
be the same as the number of columns. 

Find the inverse of the matrix shown below. Check that when the inverse is multiplied by the 
matrix itself, the result is an identity matrix. 



Original 



2 3 
4 5 
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The following program provides a solution to the problem: 

100 OPTION BASE 1 

110 DIM Original (2, 2) .Inverse (2 ,2), Identity (2, 2) 

120 ! 

130 ! Elements of Original matrix. 

140 DATA 2,3,4,5 

150 MAT READ Original 

160 IMAGE 3D.D 

170 MAT PRINT USING 160 ; Original 

180 PRINT 

190 ! 

200 MAT Inverse=INV (Original) 

210 MAT PRINT USING 160 ; Inverse 

220 PRINT 

230 ! 

240 MAT Identity=Inverse*Original 

250 MAT PRINT USING 160 ; Identity 

260 ! 

270 END 

Here are the results of executing the program: 



2.0 


3.0 


4.0 


5.0 


-2.5 


1.5 


2.0 


-1.0 


1.0 


0.0 


0.0 


1.0 



The first four elements are the contents of matrix Original. The next group of four elements are 
the inverted contents of matrix Original. The last group of four elements show that the product 
of Original and inverse of Original is indeed an identity matrix. 

You can also multiply the inverse of a matrix by another matrix using just one MAT statement. 
The syntax for this type of operation is as follows: 

MAT Result = INV (Operandi) * 0perand2 

When the determinant of a matrix is zero, the matrix does not have an inverse. Therefore, if 
you attempt to find the inverse of such a matrix using the MAT. . .INV statement, Error 112: 
DETERMINANT IS ZERO is reported. You can use the DET (determinant) function to check the 
determinant before attempting to invert a matrix. 
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Calculating the inverse of a matrix is typically done in the process of solving the matrix equation: 
Coefficients * Unknowns = Constants. However, a more accurate solution than the one provided 
by MAT Unknown = INV (Coefficients) ^Constants can be obtained using the MAT. . .SYS state- 
ment, which is described in the next section. 

Solving a System of Linear Equations 

Suppose that you have a system of n linear equations with n unknowns. Here is the general 
system: 



c(U)*x(l) + 
c(2,l)*x(l) + 



c(l,2)*x(2) 
c(2,2rx(2) 



c(l,n)*x(n) 
c(2,n)*x(n) 



= k(l) 
= k(2) 



c(n,l)*x(l) + c(n,2)*x(2) 



+ c(n,n)*x(n) 



k(n) 



It can also be expressed using this matrix notation: 
C*X = K 



in which: 



C 



c(l,l) c(l,2) . . . c(l,n) 
c(2,l) c(2,2) . . . c(2,n) 



c(n,l) c(n,2) . . . c(n,n) 



X = 



x(D 
x(2) 



x(n) 



andK = 



k(D 
k(2) 



k(n) 



C is the coefficient array; K is the constant array. The solution to this system of equations is 
the set of elements of array X. 

The MAT . . . SYS statement is used to solve the matrix equation: 

MAT X = SYS(C.K) 
for the array X. 



4-66 Numeric Computation 



The following example illustrates the use of MAT. . .SYS in solving this system of equations: 
2x + y - z = 
x - y + z = 6 
x + 2y + z = 3 

First express the system of equations in matrix notation AX = B: 



C = 



2 1-1 
1 -1 1 
1 2 1 



X 



, andK 



The program to solve this system of equations is as follows: 



100 


OPTION BASE 1 


110 


DIM C(3,3),X(3),K(3) 


120 


i 


130 


! Read coefficient matrix 


140 


DATA 2,1,-1,1,-1,1,1,2,1 


150 


MAT READ C 


160 


! Read constant vector. 


170 


DATA 0,6,3 


180 


MAT READ K 


190 


! 


200 


! Solve the equations. 


210 


MAT X=SYS(C,K) 


220 


i 


230 


! Display solution. 


240 


MAT DISP X 


250 


! 


260 


END 



Here are the results from executing the program: 

2 

-1 
3 

The value of x is 2, the value of y is -1, and the value of z is 3. 

As mentioned earlier, the solution to the matrix equation C*X = K can also be obtained using 
the statement MAT X = INV(C)*K. The solution obtained using the statement MAT X = SYS(C.K) 
is somewhat more accurate; however, to achieve this accuracy two extra blocks of memory are 
used, each the size of the array X. 
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Although in typical applications the result array X and constant array K are each vectors or one- 
column matrices, the MAT. . .SYS statement does not restrict these arrays to only one column. 
This allows you, for example, to simultaneously solve two different systems of n equations in n 
unknowns, provided that the coefficients in both systems of equations are identical. 

A useful example of this is described in the following problem. Your company's publications 
manager wants to determine the cost factors used by two outside printers. Each printer estimates 
jobs based on these criteria: 

• The number of pages. 

• The number of photographs. 

• A fixed setup charge. 

Here are estimates obtained from two printers for jobs that have varying numbers of pages and 
photographs. 

Table 4-7. Printer Jobs 





Numbers 


Number of 


Total Cost 


Jobs 


of Pages 


Photographs 


Printer 


Printer 2 


1 


273 


35 


$5835.00 


$7362.50 


2 


150 


8 


$3240.00 


$4085.00 


3 


124 


19 


$2775.00 


$3517.50 



Given the three estimates from each printer shown in the table above, you need to develop a 
program that calculates the printer's charge per page, cost per photograph, and once-per-job 
setup charge. 

To solve the problem, you can set up the following system of equations for two sets of cost 
estimates: 

273*x(l) + 35*x(2) + l*x(3) = Estimated Printer) 

150*x(l) + 8*x(2) + l*x(3) = Estimate(2,Printer) 

124*x(l) + 19*x(2) + l*x(3) = Estimated, Printer) 

These equations can be represented in matrix notation as follows: 
Items* Cost Factors = Estimates 
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Items is the coefficient matrix containing the number of items for each job. 
273 35 1 



Items = 



150 
124 



19 



Each row contains data for a different job. Column 1 of each row contains the number of pages 
for the job. Column 2 of each row contains the number of photographs for the job. Column 3 
of each row contains the number of setup charges for the job. 

Estimates is the constant array that contains the cost estimates of three jobs (from two printers). 
5835.00 7362.50 



Estimate = 



3240.00 
2775.00 



4085.00 
3517.50 



Each row contains cost estimates for one job. Column 1 contains printer l's cost estimates for 
each job. Column 2 contains printer 2's cost estimates for each job. 

CostFactors is the array that contains the unknown cost factors: x(l) is the cost per page, x(2) 
is the cost per photograph, and x(3) is the setup charge. 

Since you are solving two systems of equations, the result array CostFactors must be a matrix; 
that is, it should originally be declared with two dimensions. (If CostFactor is not the same size 
as that of the constant array Estimates, then it is automatically redimensioned to the size of 
Estimates before the MAT. . .SYS statement is executed.) Each column contains the cost factors 
for one printer. 
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A program to solve this manager's problem is listed below: 

100 OPTION BASE 1 

110 DIM Items (3, 3) ,CostFactors(3,2) .Estimates (3, 2) 

120 ! 

130 ! Items for job 1. 

140 DATA 273,35,1 

150 ! Items for job 2. 

160 DATA 150,8,1 

170 ! Items for job 3. 

180 DATA 124,19,1 

190 MAT READ Items 

200 ! 

210 ! Estimates for job 1. 

220 DATA 5835,7362.5 

230 ! Estimates for job 2. 

240 DATA 3240,4085 

250 ! Estimates for job 3. 

260 DATA 2775,3517.5 

270 MAT READ Estimates 

280 ! 

290 ! Calculate cost factors. 

300 MAT CostFactors=SYS( Items, Estimates) 

310 ! 

320 ! Now print results. 

330 PRINT "Printer 1 Printer 2" 

340 PRINT " " 

350 MAT PRINT USING "X,3D.2D,6X,3D.2D" ; CostFactors 

360 ! 

370 END 

The program displays the cost factors for each printer: 
Printer 1 Printer 2 



20.00 


25.00 


5.00 


7.50 


200.00 


275.00 



The first line of the table displayed above gives the cost per page. The second line gives the 
cost per photograph. The final line of the table gives the setup charge. 
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Additional Array Functions 

Technical BASIC provides several functions that deal with numeric arrays. For instance, pre- 
ceding sections gave examples of LBND, UBND, and DET. This section describes the array-related 
numeric functions that have not yet been described. 

In the following descriptions, the variable(s) shown in parentheses (such as Array and Subscript) 
signify that the function requires numeric argument(s), which can be any numeric expression. 



Function 

ABSUM (Array) 

AMAX (Array) 
AMAXCOL 

AMAXROW 

AMIN (Array) 
AMINCOL 

AMINROW 

CNORM (Array) 

CNORMCOL 

DET (Matrix) 
DETL 

D0T(Vectorl,Vector2) 
FNORM (Array) 

LBND 
(Array , Subscript) 

MAXAB (Array) 



Description 

Returns the sum of the absolute values of all the elements in Array. 

Returns the value of the largest element in Array. 

Returns the number of the column which contained the largest element 
in the array specified in the last AMAX function. 

Returns the number of the row which contained the largest element in 
the array specified in the last AMAX function. 

Returns the value of the smallest element in Array. 

Returns the number of the column which contained the smallest ele- 
ment in the array specified in the last AMIN function. 

Returns the number of the row which contained the smallest element 
in the array specified in the last AMIN function. 

Returns the column norm of Array — the largest sum of absolute 
values obtained by summing the absolute values of elements in each 
column of the array. 

Returns the number of the column (of the array specified in the last 
CNORM function) which contained the largest sum of absolute values. 

Returns the determinant of Matrix, which must be a square matrix. 

Returns the determinant of the matrix which was last inverted. (Matri- 
ces are inverted by the MAT. . . INV and MAT. . .SYS statements). 

Returns the inner (dot) product of the two vectors. 

Returns the square root of the sum of the squares of all elements in 
Array. This value is known as the Froebenius or Euclidian norm. 

Returns the lower bound of Subscript in Array (i.e., the current OP- 
TION BASE). 

Returns the largest absolute value of any element in Array. 



Numeric Computation 4-71 



MAXABCOL 
MAXABROW 
RNORM (Array) 

RNORMROW 

SUM (Array) 

UBND 
(Array , Subscript) 



Returns the number of the column which contained the largest absolute 
value of any element in the array specified in the last MAXAB function. 

Returns the number of the row which contained the largest absolute 
value of any element in the array specified in the last MAXAB function. 

Returns the row norm of Array — the largest sum of absolute values 
obtained by summing the absolute values of elements in each row of 
the array. 

Returns the number of the row which contained the largest sum of 
absolute values in the array specified in the last RNORM function. 

Returns the sum of all the elements in Array. 

Returns the upper bound of Subscript in Array. 
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String Manipulation 



5 



Introduction 

It is often desirable to store non-numerical information in the computer. For instance, you will 
often need to store and manipulate alphanumeric characters (text) with programs. This chapter 
describes several techniques for working with string data. 

Chapter Contents 

The sections of this chapter cover the following topics: 



Tasks/ Topics 


Page 


What is a string? 


5-2 


Evaluating string expressions 


5-4 


Substrings 


5-6 


String-related functions 


5-9 


Number-base conversions 


5-11 


Additional string functions 


5-14 


User-defined string functions 


5-16 


String array operations 


5-17 
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What is a String? 

A string is defined as any sequence of characters. A word, a name, or a message can be stored 
in the computer as a string. Each character in a string is stored as an eight-bit quantity; thus, 
there are 255 different characters available with Technical BASIC. 

Assigning Values to String Variables 

The following are valid assignments to sting variables. Quotation marks are used to delimit the 
beginning and ending of the string. 

LET StringVariable$=" computer" 
Fail$="The test has failed." 
FileName$=" INVENTORY" 
Test$=Fail$[5,8] 

The left-hand side of the assignment (the variable name) is assigned the string value on the 
right-hand side of the assignment (the literal). 

String Variable Names 

String variable names are identical to numeric variable names with the exception of a dollar sign 
($) appended to the end of the name. They may contain up to 32 characters, including all letters 
of the alphabet (both uppercase and lowercase), decimal digits through 9, and the under bar 
(_) character. Just about the only restriction on string variable names is that the first character 
must be an alphabetic character. 

String Variable Lengths 

The length of a string is the number of characters in the string. In the previous example, the 
length of StringVariable$ is 8, since there are eight characters in the string literal "computer". 

BASIC allows the dimensioned length of a string to range from 1 to 65 530 characters; the 
current length (number of characters in the string) can range from to the dimensioned length. 
A string of zero characters is often called a null string or an empty string. 

The default dimensioned length of a string is 18 characters. The DIM and COM statements are 
used to define string lengths up to the maximum length of 65 530 characters. An error results 
whenever a string variable is assigned more characters than its dimensioned length. 

A string may contain any character. The only special case is when a quotation mark needs to 
be in a string. A quote preceded by the tilde character will embed a quote within a string. 
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10 Quote$="The time is ~"N0W~"." 
20 PRINT Quote$ 
30 END 

Produces: The time is "NOW" . 

Dimensioning String Variables 

Strings whose length exceeds the default length of 18 characters must have space reserved 
before assignment. The following statements may be used. 

DIM Long$ [400] Reserves memory for a 400-character string. 

COM Line$ [80] Reserves memory for an 80-character string variable in "common" storage. 

The maximum length of any string must not exceed 65 530 characters. A string may also be 
dimensioned to a length less than the default length of 18 characters. 

Simple String Variables 

The DIM statement reserves storage for simple string variables. 

DIM Part_number$[10] .Descriptions [64] ,Cost$[5] 

The COM statement defines common variables that can be used by subprograms and chained 
programs. 

COM Name$[40] ,Phone$[14] 
Strings that have been dimensioned but not assigned values contain the null string. 

String Arrays 

Large amounts of text are easily handled in arrays. For example: 

DIM File$(1000) [80] 

This statement reserves storage for 1000 lines of 80 characters per line. Do not confuse the 
brackets, which define the length of each string array element, with the parentheses, which define 
the number of strings in the array. Each string in the array can be accessed by a subscript. For 
example: 

PRINT File$(27) 

Prints element 27 of the array. Since each character in a string uses one bytes of memory and 
each string in the array is allocated as many bytes as the maximum length of the string, string 
arrays can quickly use a lot of memory. 



String Manipulation 5-3 



Evaluating String Expressions 

This section describes how the Technical BASIC system evaluates string expressions. 

Evaluation Hierarchy 

Evaluation of string expressions is simpler than evaluation of numerical expressions. The three al- 
lowed operations are extracting a substring, concatenation, and parenthesization. The evaluation 
hierarchy is presented in the following table. 

Table 5-1. Evaluation Hierarchy 



Order 


Operation 


High 
Low 


Parentheses 

Substrings and Functions 

Concatenation 



String Concatenation 

Two separate strings are joined together by using the concatenation operator "&". The following 
program combines two strings into one. 

100 0ne$= "WRIST" 

110 Two$= "WATCH" 

120 Concat$=0ne$&Two$ 

130 PRINT 0ne$,Two$,Concat$ 

140 END 



Prints: 

WRIST 



WATCH 



WRISTWATCH 



The concatenation operation, in line 30, appends the second string to the end of the first string. 
The result is assigned to a third string. An error results if the concatenation operation produces 
a string that is longer than the dimensioned length of the string being assigned. 
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Relational Operations 

Most of the relational operators used for numeric expression evaluation can also be used for the 
evaluation of strings. 

The following examples show some of the possible tests. 

"ABC" = "ABC" True 

"ABC" = " ABC" False 

"ABC" < "AbC" True 

"6" > "7" False 

"long" <= "longer" True 

"RE- SAVE" >= "RESAVE" False 

Any of these relational operators may be used: <, >, <=, >=, =, <>. 

Testing begins with the first character in the string and proceeds, character by character, until 
the relationship has been determined. 

The outcome of a relational test is based on the characters in the strings, not on the length of 
the strings. For example: 

"BRONTOSAURUS" < "CAT" 
This relationship is true since the letter "C" is greater in ASCII value than the letter "B". 
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Substrings 

A subscript can be appended to a string variable name to define a substring. A substring may 
comprise all or just part of the original string. Brackets enclose the subscript which can be a 
constant, variable, or numeric expression. For instance: 

String$[4] Specifies a substring starting with the fourth character of the String$ variable, 
and continuing through the end of the variable's current contents. 

Note that the brackets now indicate the substring's starting position, instead of the total length 
of the string as when reserving storage for a string. The subscript must be in the range: 1 to 
the string's current length (not dimensioned length). Any subscript value larger than this causes 



Subscripted strings may appear on either side of the assignment. 

Single-Subscript Substrings 

When a substring is specified with only one numerical expression, enclosed with brackets, the 
expression is evaluated and rounded to an integer indicating the position of the first character 
of the substring within the string. 

The following examples use the variable A$ which has been assigned the literal "DICTIONARY". 



Statement 


Output 


PRINT A$ 


DICTIONARY 


PRINT A$[0] 


(error) 


PRINT A$[l] 


DICTIONARY 


PRINT A$[5] 


IONARY 


PRINT A$[10] 


Y 


PRINT A$[ll] 


(error) 



When a single subscript is used it specifies the starting character position of the substring, within 
the string. An error results when the subscript evaluates to zero or greater than the current 
length of the string. 
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Double-Subscript Substrings 

A substring may have two subscripts, within brackets, to specify a range of characters. When 
a comma is used to separate the items within brackets, the first subscript marks the beginning 
position of the substring, while the second subscript is the ending position of the substring. The 
form is: String$ [Start .End] 

LET StriIlg$="JABBERWOCKY ,, 

PRINT String$ [4,6] 

BER 

In the following examples the variable B$ has been assigned to the literal "ENLIGHTENMENT": 



Statement 


Output 


PRINT B$ 


ENLIGHTENMENT 


PRINT B$[l,13] 


ENLIGHTENMENT 


PRINT B$[l,9] 


ENLIGHTEN 


PRINT B$[3,7] 


LIGHT 


PRINT B$[4,4] 


I 


PRINT B$ [13,26] 


(error) 



An error results if either the first or the second subscript is greater than the current string length. 

Special Considerations 

All substring operations allow a subscript to specify the first position past the end of a string. 
This allows strings to be concatenated without the concatenation operator. For instance: 

100 A$="C0NCAT" 
110 A$[7]= ,, ENATI0N" 
120 PRINT A$ 
130 END 

Produces: CONCATENATION 

The substring assignment is only valid if the substring already has characters up to the specified 
position. Access beyond the first position past the end of a string results in the insertion of blank 
spaces. 

It is a good practice to dimension all strings including those shorter than the default length of 
eighteen characters. This helps to manage the amount of memory space used by a string so 
that no memory space is wasted. 
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Some very interesting assignments can be attempted. For example, a 14-character string can be 
assigned to a 3-character substring. 

100 Big$="Too big to fit" 

110 Small$="Little string" 

120 ! 

130 Small$[l,3]=Big$ 

140 ! 

150 PRINT Small$ 

160 END 

Prints: Tootle string 

When a substring assignment specifies fewer characters than are available, any extra trailing 
characters are truncated. 

The alternate assignment is shown in the next example. Here a 4-character string is assigned to 
a 8-character substring. 

100 Big$="A large string" 

110 Small$="tiny" 

120 ! 

130 Big$[3,10]=Small$ 

140 ! 

150 PRINT Big$ 

160 END 

Prints: A tiny ring 

Since the subscripted length of the substring is greater than the length of the replacement string, 
enough blanks (ASCII spaces) are added to the end of the replacement string to fill the entire 
specified substring. 
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String-Related Functions 



Several intrinsic functions are available in BASIC for the manipulation of strings. These functions 
include conversions between string and numeric values. 

String Length 

The "length" of a string is the number of characters in the string. The LEN function returns an 
integer whose value is equal to the string length. The range is from (null string) thru 65 530. 
For example: 

PRINT LEN ("HELP ME") 

Prints: 7 

The following example program prints the length of a string that is typed on the keyboard. 

100 DIM In$[160] 

110 INPUT In$ 

120 Length=LEN(In$) 

130 DISP Length; "characters in ";In$ 

140 END 

Try finding the length of a string containing only spaces. When the INPUT statement is used, 
any leading or trailing spaces are removed from items typed on the keyboard. Change INPUT to 
L INPUT in line 20 to allow leading and trailing spaces to be entered. 

Substring Position 

The "position" of a substring within a string is determined by the P0S function. The function 
returns the value of the starting position of the substring or zero if the entire substring was not 
found. For instance: 

PRINT P0S( "DISAPPEARANCE" , "APPEAR") 

Prints: 4 
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The following example prints the positions of substrings found within a string. 

10 OPTION BASE 1 

20 DIM Sentences [40] ,Word$ (6) [8] 

30 DATA CAT, ON, A, HOT, TEN, NATION 

40 FOR 1=1 TO 6 @ READ Word$(I) @ NEXT I 

50 Sent ence$= "WHERE IS THE CAT IN CONCATENATION" I 

60 ! 

70 FOR 1=1 TO 6 

80 Position=POS (Sentences, Word$ (I)) ! <- POS function 

90 IF Position THEN SEG1 ELSE SEG2 

100 SEG1: 

110 PRINT Sentence$ 

120 PRINT TAB (Position) ;Word$ (I) ;TAB(35);"is at ";Position 

130 PRINT GOTO 170 

140 SEG2: 

150 PRINT " ' " ; Word$ (I) ; " ' was not found" 

160 PRINT 

170 ! End of multi-line IF. . .THEN. . .ELSE construct. 

180 NEXT I 

190 END 

If POS returns a non-zero value, the entire substring occurs in the first string and the value 
specifies the starting position of the substring. 

Note that POS returns the first occurrence of a substring within a string. By adding a subscript, ( 
and indexing through the string, the POS function can be used to find all occurrences of a 
substring. The following program uses this technique to extract each word from a sentence. 

100 DIM A$[80] 

110 A$="I know you think you understand what I said, but you don't." 

120 INTEGER Scanner, Found 

130 Scanner=l ! Current substring position 

140 PRINT A$ 

150 REPEAT: 

160 Found=P0S (A$ [Scanner] , " ") ! Find the next ASCII space 

170 IF Found THEN SEG1 ELSE SEG2 

180 SEG1: 

190 PRINT A$ [Scanner, Scanner+Found-1] ! Print the word 

200 Scanner=Scanner+Found @ GOTO 140 ! Adjust "Scan" past last match 

210 SEG2: 

220 PRINT A$ [Scanner] ! Print last word in string 

230 IF Found THEN REPEAT ! End of REPEAT construct. 

240 END 

As each occurrence is found, the new subscript specifies the remaining portion of the string to 
be searched. 
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String-to-Numeric Conversion 

The VAL function converts a string expression into a numeric value. The string must evaluate 
to a valid number or error 89 will result. 

Error 89 INVALID PARAM 

The number returned by the VAL function will be converted to and from scientific notation when 
necessary. For example: 

PRINT VAL("123.4E3") 

Prints: 123400 

The following program converts a fraction into its equivalent decimal value. 

100 PRINT "Enter a fraction (i.e. 3/4)" 

110 INPUT Fraction$ 

120 ! 

130 ON ERROR GOTO Err 

140 Numerator=VAL (Fraction$) 

150 ! 

160 IF P0S (Fractions,"/") THEN SEG1 ELSE SEG2 

170 SEG1: 

180 Delimiter=P0S (Fractions,"/") 

190 Denominator=VAL (Fractions [Delimiter+1] ) 

200 GOTO 240 

210 SEG2: 

220 PRINT "Invalid fraction" 

230 GOTO Err 

240 ! End of multi-line IF. . .THEN. . .ELSE construct. 

250 ! 

260 PRINT Fractions," = "; Numerator/Denominator 

270 GOTO Quit 

280 Err: PRINT "ERROR Invalid fraction" 

290 OFF ERROR 

300 Quit: END 

Similar techniques can be used for converting: feet and inches to decimal feet or hours and 
minutes to decimal hours. 

The NUM function converts a single character into its equivalent numeric value. The number 
returned is in the range: to 255. For example: 

PRINT NUM ("A") 

Prints: 65 
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The next program prints the value of each character in a name. 

100 PRINT "Enter your first name." 

110 INPUT Name$ 

120 PRINT Name$ 

130 PRINT 

140 FOR 1=1 TO LEN(Narae$) 

150 PRINT NUM(Name$[I]) ; ! Print value of each character 

160 NEXT I 

170 PRINT 

180 END 

Entering the name: JOHN will produce the following. 

JOHN 
74 79 72 78 

Numeric-to-String Conversion 

The VAL$ function converts the value of a numeric expression into a character string. The string 
contains the same characters (digits) that appear when the numeric variable is printed. For 
example: 

PRINT 10000000000000000 , VAL$ ( 10000000000000000) 

Prints: le+016 le+016 

Note that scientific notation does not start until there are seventeen digits to the left of the 
decimal point. 

The next program converts a number into a string so the POS function can be used to separate the 
mantissa from the exponent. Note that this program only works with large positive exponents 
of size 16 or greater. For example, enter the following program: 

100 PRINT 

110 PRINT "Enter a number with an exponent" 

120 INPUT Number 

130 ! 

140 Number$=VAL$ (Number) 

150 ! 

160 PRINT Number$ 

170 E=P0S (UPC$ (NumberS) ,"E") 

180 IF E THEN SEG1 ELSE SEG2 

190 SEG1: 

200 PRINT "Mantissa is" ,Number$[l ,E-1] 

210 PRINT "Exponent is" , NumberS [E+l] 

220 GOTO Quit 

230 SEG2: 

240 PRINT "No exponent" 

250 GOTO Quit 

260 Quit: END 
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The program when executed prompts you with the following: 
ENTER A NUMBER WITH AN EXPONENT 

Enter the following number with its exponent: 



3E+16 Return 



This returns: 




3e+016 

MANTISSA IS 
EXPONENT IS 


3 
+016 



The CHR$ function converts a number into an ASCII character. The number can be of type 
INTEGER or REAL since the value is rounded, and a modulo 255 is performed. For example: 

PRINT CHR$(97);CHR$(98) ;CHR$(99) 

Prints: abc 

The next program prints the values in the data statement as characters. 

100 OPTION BASE 1 

110 PRINT 

120 CLEAR 

130 ! 

140 DATA 34,89,111,117,32,103,111,116,32,105,116,33,34 

150 INTEGER N(13) 

160 MAT READ N 

170 FOR 1=1 TO 13 

180 PRINT CHR$(N(I)); 

190 NEXT I 

200 PRINT CHR$(7) 

210 END 
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String Functions 

Several additional string functions are available when using HP-UX Technical BASIC. This sections 
provides examples of these functions and a sample user-defined string function. , 

\ 

String Reverse 

The REV$ function returns a string created by reversing the sequence of characters in the given 
string. 

PRINT REV$(" Snack cans") 

Prints: snac kcanS 

A common use for the REV$ function is to find the last occurrence of an item in a string. 

100 DIM List$[30] 

110 List$="3.22 4.33 1.10 8.55 12.20 1.77" 

120 Length=LEN(List$) 

130 Last_space=POS(REV$(List$)," ") 

140 DISP "The last item is : " ;List$[l+Length-Last_space] 

150 END 

Displays: The last item is: 1.77 

String Repeat ( 

The RPT$ function returns a string created by repeating the specified string, a given number of 
times. 

PRINT RPT$("* *",10) 

Prints: * ** ** ** ** ** ** ** ** ** * 

Here is a short program that uses RPT$ to create an image for a formatted print statement. 

100 OPTION BASE 1 

110 DATA 50,900,2,444,37,2001,32768 

120 DIM Array (7) 

130 MAT READ Array 

140 Maxdigits=0 

150 FOR 1=1 TO 7 

160 Digits=INT(l+LGT(Array(I))) 

170 IF Digits>Maxdigits THEN Maxdigits=Digits 

180 NEXT I 

190 Form$="XX,"&RPT$("D",Maxdigits)&".DD" / 

200 PRINT "Using the image: ";Form$ ^ 

210 MAT PRINT USING Form$ ; Array 

220 END 
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Trimming a String 

The TRIMS function returns a string with all leading and trailing blanks (ASCII spaces) removed. 

PRINT ,l *" ; TRIMS (" 1.23 ");"*" 

Prints: *1.23* 

TRIMS is often used to extract fields from data statements or keyboard input. 

100 DISP "Enter your first and last name." 

110 INPUT NameS 

120 First$=TRIM$ (NameS [1.P0S (NameS," ")]) 

130 Last$=TRIM$ (NameS [1+LEN (NameS) -P0S (REVS (NameS) , " " ) ] ) 

140 PRINT NameS, LEN (NameS) 

150 PRINT LastS, LEN (LastS) 

160 PRINT FirstS, LEN (FirstS) 

170 END 

If you need to enter leading or trailing spaces, use the LINPUT statement. 

Lettercase Conversion 

The lettercase conversion functions, UPCS and LWC$, return strings with all characters converted 
to the same lettercase. UPCS converts all lowercase characters to their corresponding upper- 
case characters, and LWC$ converts any uppercase characters to their corresponding lowercase 
characters. 

100 DIM Word$[160] 

110 LINPUT "Enter a few characters on this line: ",Word$ 

120 PRINT 

130 PRINT "You typed: ";Word$ 

140 PRINT "Uppercase: " ;UPC$(Word$) 

150 PRINT "Lowercase: " ;LWC$(Word$) 

160 END 
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User-Defined String Functions 

Many string functions not provided by Technical BASIC can be implemented separately as user- 
defined functions. The following program contains a string function. 

100 DEF FNStmt$(X) = "Account #"&VAL$(X) 

110 Ac ctnum= 10699 

120 DISP FNStmt$(Acctnum) 

130 END 

The results after executing this program are: 
Account #10699 

For a detailed discussion on user-defined string functions, read the chapter entitled "User-Defined 
Functions and Subprograms". 
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String Arrays 

A string array is collection of character strings collected under the same string variable name and 
having the same maximum length. The computer allows both one- and two-dimensional string 
arrays. 

Dimensioning String Arrays 

The DIM statement is used to set the upper bounds of the string array and to specify the maximum 
number of characters in each element. 

DIM Stringl$(25) [20] ,String2$(15 ,15) [20] 

The one-dimensional array Stringl$ has an upper bound of 25 and a length per element of 20. 
The two-dimensional array String2$ has an upper bound of 15 for both its rows and columns 
and a length per element of 20. Note that the upper bound(s) and length per element cannot 
exceed 65530. The lower bound of a string array is determined by the OPTION BASE of the 
program. The OPTION BASE has no effect on the maximum string length. 

String arrays, numeric arrays, and simple variables can be dimensioned in the same DIM state- 
ment. For example: 

10 OPTION BASE 

20 REM NAMES$ has 11 elements, each with maximum length of 25 characters. 

30 REM GRADES has 66 REAL numeric elements. 

40 DIM NAMES$(10) [25] , GRADES(10,5) 



If a string array is not explicitly dimensioned, it is implicitly dimensioned with upper bound(s) 
equal to 10 and maximum string length equal to 18. 

The COM statement is used to dimension string arrays which are to be preserved in common 
between chained programs. 
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String Expressions and Operations 

All the operations and functions provided for manipulating simple string variables can also be 
used with elements of string arrays. 

Operations Examples 

Assignment STRINGS ( 1) =" eclipse" 

STRINGS (2)="lunar" 
STRINGS (3) ="75" 

Concatenation EVENT$=STRING$(2) & " " & STRINGS (1) 

DISP EVENTS 
lunar eclipse 

Substring MOUTH$=STRING$ ( 1 ) [3 , 5] 

DISP MOUTHS 
lip 

Modification STRINGS (2) [1,3]=" sol" 

DISP STRINGS (2) 
solar 

Comparison STRINGS (2) < STRINGS (1) 
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Functions 


Examples 


LEN 


LEN (STRINGS (1)) 
7 


POS 


PLACE= POS(STRING$(l),"p") 




DISP PLACE 
5 


VAL 


DISP VAL (STRINGS (3)) 




75 


VAL$ 


STRINGS (4) =VAL$ (12345) 




DISP STRING$(3)&STRING$(4) 




7512345 


CHR$ 


STRINGS (5) =CHR$ (40) 




DISP STRINGS (5) 
( 


NUM 


DECVAL=NUM (STRINGS (3) ) 




DISP DEC VAL 




55 


UPC$ 


SUN$=UPC$ (STRINGS (2) ) 




SUNS 




SOLAR 
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The following program sorts a list of words alphabetically. Since string comparisons are based 
on the decimal codes assigned to each letter, all lowercase letters are converted to uppercase 
letters before sorting begins. 



100 OPTION BASE 1 

110 DIM Word$ (20) [30] ! 

120 FOR 1=1 TO 16 ! 

130 READ Word$(I) 

140 Word$(I)=UPC$(Word$(I)) 

150 PRINT Word$(I) ;" "; 

160 NEXT I ! 

170 PRINT 

180 FOR J=2 TO 16 ! 

190 Temp$=Word$(J) 

FOR I=J-1 TO 1 STEP -1 

IF Temp$>=Word$(I) THEN GOTO Insert 

Word$(I+l)=Word$(I) ! Move element down one position 



Dimensions 20- element string array. 
This loop reads and prints DATA. 

Converts word to all uppercase letters. 

End loop. 

Begin sort . 



200 

210 

220 

230 NEXT I 

240 Insert: Word$(I+l)=Temp$ 

250 NEXT J 

260 FOR 1=1 TO 16 ! 

270 PRINT Word$(I) ; " " ; 

280 NEXT I 

290 PRINT 

300 DATA HOW, CAN, you, BE, IN, TWO, PLACES, AT, once, WHEN, YOU, ARE 

310 DATA not, ANYWHERE, AT, ALL 

320 END 



Insert element at position 1+1 



Print sorted list. 
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User-Defined Functions 
and Subprograms 



6 



Introduction 

It is often handy to write algorithms that can be used in several places in a program or by other 
programmers. The "Program Structure and Flow" chapter described using subroutines for this 
purpose. Another handy feature of subroutines is that you can use them to "hide the details" 
of performing tasks from the "main" algorithm, so as not to obscure the readability of the main 
algorithm. 

User-defined functions and subprograms also accomplish these two tasks, but they provide many 
additional capabilities. This chapter describes these two powerful features of the Technical 
BASIC language. 

Chapter Contents 

This chapter discusses the following topics. 



Tasks/ Topics 
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Introduction to user-defined functions 
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Passing parameters 
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Multiple-line functions 
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6-8 


Benefits of using subprograms 
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Deleting, loading, and editing subprograms 
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Program/subprogram communication 


6-19 


Passing parameters 


6-19 


Using COM variables 


6-27 


Using system flags 


6-30 


Memory management with subprograms 


6-34 


Context switching 
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User-Defined Functions 

This section reviews some resident functions and then introduces you to user-defined functions. 
It describes several aspects of creating and using user-defined functions. 

Review of Resident Functions 

There are several resident functions built into the Technical BASIC language. Here are some 
examples: 

Y=SIN(X+Phase) 

Root 1= (-B+SQR (B*B-4*A*C) ) / (2*A) 

DISP "The value of pi = " ,PI 

PRINT "ASCII code = "; Number;" Character = " ;CHR$( Number) 

In the first example, the SIN function calculates the sine of the argument X and returns the value 
so that it can be added to the value of the variable named Phase, and the sum then assigned to 
the variable Y. 

In the second example, the SQR function calculates the square root of the argument B*B-4*A*C, 
which is then added to the negative value of the variable B, divided by the product 2*A, and 
this value is assigned to the variable Rootl. 

In the third example, the constant function PI returns the value 3.141 592 653 589 79, which 
is then displayed following the text. 

In the fourth example, the CHR$ string function takes the numeric argument Number and returns 
the corresponding ASCII character. 

Note that in all examples, the functions return a single value. 
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Introduction to User-Defined Functions 

You can also define your own functions, which effectively allows you to extend the language if 
you need a function not provided in BASIC. Here are two examples: 

X=l/FNSinh(Y~4) 
Angle=FNAtn2(Y,X) 

A general rule of thumb for using subprograms is that if you want to take a set of data and 
analyze it to generate a single value, then you probably want to define a function. On the other 
hand, if you want to actually change the data itself, generate more than one value, or perform 
any sort of I/O activity, it is better to use a subprogram. (A subsequent section describes 
subprograms.) 

With this system, you can define either single-line or multi-line functions. Let's first look at an 
example of a single-line function. 

Example Constant Function 

Here is an example of a user-defined string function that returns a constant. 
DEF FNName$="John Doe" 

Since a constant function always returns the same value, there is no "argument" to be sent to 
it. Here are examples of using the function: 

DISP "His name is ";FNName$ 

105 IF LEN(Name$)=0 THEN StudentName$(N)=FNName$ 



NOTE 

Functions can be defined anywhere in a program. They need not appear 
before they are referenced. 



Let's look at a more common example — a function with argument(s). 
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Passing Parameters to Functions 

The following line defines a function that computes the area of a circle, when supplied with a 
radius (the "argument"). 

50 DEF FNArea (Radius) =PI*Radius~2 

Here are examples of invoking the function: 

100 DISP "The area of a circle of radius 10 = ";FNArea(10) 
250 Total.Ar ea=FNArea (Rl) +FNArea (R2) +FNArea (R3) 

Note that a numeric value was "passed" to the function each time it was called: the function 
call in line 100 passed a value of 10; the function calls in line 250 passed values of variables 
Rl, R2, R3. These values are known as pass parameters. 

The variable named Radius in the Area function is known as a formal parameter. It specifies the 
variable in the function that is to receive the value passed to the function. 

Parameter Lists 

From the preceding example, it is clear that there are two types of parameter lists: 

• Formal parameter lists 

• Pass parameter lists 

The formal parameter list shows how many values may be passed to a function and gives the 
names the function will use to refer to those values. The formal parameter list for this example 
function: 

50 DEF FNArea (Radius) =PI*Radius~2 

is simply (Radius) — it is a list with one element. 

The pass parameter list specifies the value(s) to be sent to the function. The pass parameter list 
for the following function call: 

FNArea(lO) 

is simply (10). 
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Each parameter in the pass parameter list corresponds to a parameter in the formal parameter 
list provided by the function. The function has the power to demand that the function call match 
the types declared in the formal parameter list exactly — otherwise an error results. It is also 
perfectly legal for both the formal and pass parameter lists to be null (non-existent), as long as 
both match. 

Single-line functions are not restricted to being passed one parameter; you can pass up to 16 
numeric or 7 string parameters. These parameters include both simple numeric and string 
variables and numeric and string arrays. 

An Example Multiple-Line Function 

Since it is difficult to implement many significant functions while limited to one line of BASIC 
code, you can also define multiple-line functions. Here is a simple example. 

110 PRINT "Decimal "."Octal" 

120 FOR Decimal_no=l TO 100 STEP 5 

130 PRINT Decimal_no,FNOctal(Decimal_no) 

140 NEXT Decimal_.no 

150 STOP 

160 ! 

170 DEF FN0ctal(Decimal_Number) 

180 0ctal_Equiv=O 

190 Remainder=Decimal_Number 

200 FOR 0ctal_Place=10 TO STEP -1 

210 0ctal_Digit=IP (Remainder/8~0ctal_Place) 

220 Remainder=Remainder MOD 8~0ctal_Place 

230 0ctal_Equiv=0ctal_Equiv+0ctal_Digit*10~0ctal_Place 

240 NEXT Octal.Place 

250 FN0ctal=0ctal_Equiv 

260 FN END 

The function's formal parameters are defined in the DEF FN statement. The value of the function 
is not defined in this declaration statement; instead, it is defined later in the function (line 250 
in this example). 
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Functions and Local Variables 

In general, all main program variables are accessible to functions. This is true whether they are 
declared explicitly (with statements such as DIM) or implicitly (for instance, numeric variables are 
assumed REAL unless explicitly declared otherwise). Here is an example: 

10 Scale_factor=2 

20 DEF FNXyz(Arg)=Scale_factor*Arg~3 

30 DISP "FNXyz(2)=";FNXyz(2) 

40 END 

The results of this function call are 16 (=2*2"3) rather than 8 (=2~3). Thus, the main program's 
variable named Scale_factor was accessible to the function. 

On the other hand, all variables declared in the formal parameter list are not accessible to the 
rest of the program; they are "local" to the function. This includes function variables that have 
the same name as a main program variable. For instance, the function's Radius variable is not 
available to the main program. Here is an example: 

10 Radius=123 

20 DEF FNArea (Radius) =PI*Radius~2 

30 DISP "Result of 'Area(lO) ' =" ;FNArea(10) 

40 DISP "Main program's variable 'Radius' ="; Radius 

50 END 

Here are the results of running the program. 

Result of 'Area(lO)' = 314.159265358979 
Main Radius = 123 

In line 10, the main program assigned a value of 123 to its variable named Radius. The call to 
Area (line 30) specified that the function's variable named Radius is to be assigned a value of 
10. The results of line 30 verify that the function's variable named Radius was assigned a value 
of 10, while line 40 verifies that the main program's variable named Radius was not changed 
when the function's Radius was assigned the value of 10. 
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Formal Parameter Data-Type Declarations 

Variables can be declared either implicitly or explicitly. Here is how variables are implicitly 
declared: 

• Numeric variables are assumed to be of type REAL, unless explicitly declared INTEGER or 
SHORT. 

• String variables are dimensioned to have a maximum length of 18 characters. 

Explicit type declarations are made with DIM, REAL, SHORT, and INTEGER statements. 

Since a function's formal parameters are -local to the function, the type of each variable is 
implicitly declared in its DEF FN statement. Suppose, however, that you want to be able to pass 
a string longer than 18 characters to a function. In order to do that, you will need to declare a 
greater string length in the function heading. Here is an example: 

DEF FNDo_something$(Arg$[100])= ... 

Limitations 

Functions cannot be used recursively. For instance, a function cannot call itself nor can it call 
another function that is used in its definition. 

Functions are not restricted to being passed one parameter; you can pass up to 30 parameters to 
a user-defined function. These parameters include both simple numeric and string variables and 
numeric and string arrays. However, user-defined string functions are restricted to returning 
a maximum of 18 characters. 
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Introduction to Subprograms 

This section shows you what subprograms are and gives you a glimpse of their capabilities. You 
will see how to enter and call two simple subroutines from a program. 

Simple Examples 

As described in the Program Structure and Flow chapter, subroutines are common routines that 
can be executed by several parts of the program. Subprograms are like subroutines in this 
respect, but they are much more powerful. But before discussing the additional capabilities that 
they provide, let's take a look at some simple examples. 

Here is a "main" program that calls two subprograms. (A subsequent section shows how to 
enter, store, and load them.) 

100 DISP "This is displayed by MAIN program." 

110 DISP 

120 CALL "FirstSub" 

130 ! 

140 CALL "SecondSub" ("String pass parameter") 

150 ! 

160 DISP "This is the MAIN program again." 

170 ! 

180 END 

Here are the subprograms. 

100 SUB "FirstSub" 

110 DISP "This is displayed by 'FirstSub'." 

120 DISP 

130 SUBEND 

100 SUB "SecondSub" (Formal_param$) 

110 DISP "This is displayed by 'SecondSub'." 

120 DISP "The value sent to me is '" ;Formal_param$; " ' . " 

130 DISP 

140 SUBEND 

Here are the results of running the program. 
This is displayed by the MAIN program. 

This is displayed by 'FirstSub'. 

This is displayed by 'SecondSub' . 

The value sent to me is 'String pass parameter' . 

This is the MAIN program again. 
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Here is how the program flows. Executing RUN transfers control to the main program, beginning 
with line 100. This program line displays the first line of the results shown above. Control then 
moves to line 110 (DISP) and to line 120, which calls the subprogram named FirstSub. This 
CALL transfers control to the subprogram. 

Lines 110 and 120 of FirstSub then display the third and fourth lines of the above results. Line 
130 transfers control back to the calling context (here, the main program). 

Line 140 of the main program calls the subprogram named SecondSub. The value String pass 
parameter is passed to the subprogram; it is known as a "pass parameter." Control is then 
given to SecondSub. 

Lines 110 through 130 of SecondSub display the fifth through seventh lines of the above results; 
in particular, line 120 displays the value String pass parameter, which was passed to it by 
the main program. (You will see more about how parameters get passed in the section called 
"Program/Subprogram Communication.") Control is then returned to the calling program. 

Finally, the main program (line 160) displays the final line of the above results, and program 
execution is finished when the END statement is reached (line 180). 

These simple examples show that subprograms have several things in common with subroutines. 
Then why use subprograms? The next section provides the answer. 

Benefits of Using Subprograms 

Like subroutines, subprograms provide the main program with the ability to execute a common 
algorithm. A subprogram also depends on a main program and cannot be executed alone. It 
can execute internal subroutines, and can call other subprograms. However, subprograms also 
provide many additional capabilities. 

The main power of subprograms is provided by these two characteristics: 

• Subprograms can be handled independently — that is, they are not part of any main 
program, so they can be created, stored, and retrieved separately. 

• You can give (or deny) a subprogram access to any or all of the variables and values 
in the main program (or subprogram) that calls it. You can "pass" specific parameters 
to them, or allow them to access specific common (COM) variables. 

In short, a subprogram provides an easy way to isolate a useful programming routine, store it, 
and call it back into main memory for execution whenever needed. 
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There are several benefits to be realized by using subprograms: 

• The subprogram allows the you to take advantage of the "top-down" method of designing 
programs. In this technique, the problem to be solved is broken up into a set of smaller and 
more easily solvable problems (known as "stepwise refinement.") These smaller problems 
can in turn be broken up into smaller problems yet, and so on. This technique has been 
shown to greatly improve the design, coding, and testing of programs. 

• By separating all the details of performing the subtasks from the overall logic flow of the 
main program, the program is much easier to read (assuming you name the subprograms 
judiciously). The programmer can see at a high level what he's trying to accomplish, rather 
than immediately getting lost in the details of each little sub-task. 

• Subprograms can do everything a main program can do. A subprogram has its own 
"context," or state, which is distinct from a main program and all other subprograms. This 
means that every subprogram has its own independent set of variables, DATA blocks, line 
labels, and so forth. Thus, you don't have think about not re-using such things as variable 
names and line labels used in the main program, because there will never be a conflict. 

• One of the most time-consuming parts of writing a program is debugging it, or forcing it 
to run correctly. The time-consuming part of fixing bugs in a program is finding where the 
bug is in the first place. By using subprograms and testing each one independently, it 
is easier to locate and correct problems. (This is also known as a "bottom-up" method of 
testing.) 

• Finally, libraries of commonly used subprograms can be assembled for widespread use. 

Many different users doing diverse types of problems still may require some identical 
subprograms. 

Difference Between Functions and Subprograms 

A subprogram is invoked explicitly using the CALL statement. A user-defined function is called 
implicitly by using the function name in an expression. The function name can be used in a 
numeric or string expression the same way a resident system function or constant is used. A 
function's purpose is to return a single value (either a real number or a string). A subprogram's 
purpose is generally to calculate more than one value. 
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Creating and Calling Subprograms 

Here are the general steps that you will need to take to enter a subprogram into memory, make 
a copy of it in mass storage, and call it from a program (or subprogram): 

1. Determine what is currently in memory. (This step is optional.) 

a. Use the DIRECTORY statement to get a listing of the program and subprogram(s) 
currently in memory, if any. 

2. If an unwanted program and subprogram(s) are currently in memory, then use SCRATCH to 
erase them. 

3. Enter and store a main program (that calls a subprogram). 

a. Execute FINDPROG with no file name to "point" the editor at the main program's 
memory area. 

b. Enter the BASIC program lines, which include a CALL to the subprogram (to be 
written subsequently). 

c. Use the STORE command or SAVE statement to record a copy of the program in a 
mass storage file. 

4. Enter a new subprogram. 

a. Use FINDPROG followed by a subprogram name to point the editor at a memory area 
to be used for the new subprogram. 

b. Enter the heading by typing SUB followed by the subprogram name (and formal 
parameters, if any). 

c. Enter the rest of the BASIC code for the subprogram. 

d. End the subprogram with a SUBEND or SUBEXIT statement. 

e. Use the STORE command to record a copy of the subprogram in file. 

5. Run the main program. 
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Checking Memory Contents 

Before entering any new program or subprograms, use the DIRECTORY statement to check what 
is currently in your BASIC memory area. 

DIRECTORY 

If no main program or subprogram is currently in memory, then you should see the following 
display. 

BASIC program bytes lines allocated 
> MAIN no 

If the main program and two subprograms shown in the preceding example were in your BASIC 
memory area, then you would see something like this: 



BASIC program 


bytes 


lines 


allocated 


MAIN 


196 


9 


yes 


FirstSub 


76 


4 


yes 


SecondSub 


156 


5 


yes 



Here is a brief description of the columns of the DIRECTORY statement's results. 

BASIC program lists the name(s) of the subprogram(s) currently in <memory>. Also shows 
the size of the "MAIN" program. (There is no main program in memory of 
both the bytes and lines columns show 0). 

bytes shows the amount of memory required by the program or subprogram. 

lines shows the number of lines contained in the program or subprogram. 

allocated effectively indicates whether or not the program or subprogram has been 

"initialized" (by INIT) or run (by RUN). 

> indicates which program/subprogram can currently be edited, listed, etc. 



NOTE 

You can simultaneously have one program and several subprograms 
within the memory allocated for your use by Technical BASIC. How- 
ever, you can only "look at" one of them at a time. For instance, 
executing a LIST command would only show one of them — the one to 
which the > is pointing. More about this feature momentarily. 
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Entering a Main Program 

Now point the system editor at the main program by executing a FINDPROG statement without 
specifying a file name: 

FINDPROG 

(This is a redundant step if you just executed a SCRATCH command as shown in the preceding 
discussion.) 

Now execute this command to verify that you can enter the main program. 
DIRECTORY 

You should get this result: 

BASIC program bytes lines allocated 

> MAIN no 

The > pointing toward MAIN indicates that the main program is the one which you can now edit 
(or, in this case, the one you can enter). This is also the condition of memory at power-up. 

Now enter the lines of the example program: 

100 DISP "This is displayed by MAIN program." 

110 ! 

120 CALL "FirstSub" 

130 ! 

140 CALL "SecondSub" ("String pass parameter") 

150 ! 

160 DISP "This is the MAIN program again." 

170 ! 

180 END 

Now store the main program using either the STORE command: 

STORE "MainProg" 
or the SAVE statement: 

SAVE "MainProg" 

The differences between these methods are as follows: 

1. STORE creates a BASIC/PROG ("object") file, while SAVE creates a BASIC/DATA (ASCII 
source) file. 

2. LOAD retrieves files stored with STORE, while GET retrieves files stored with SAVE. 
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Entering a New Subprogram 

Use the FINDPROG statement again, this time to point the editor at the beginning of the memory 
area which will be used for the subprogram that you will be entering. For simplicity, let's call 
the new subprogram FirstSub. 

FINDPROG "FirstSub" 

The system should respond with this message: 
New program 



NOTE 

If a subprogram file (of type BAS1C/SUBP) with this name already 
exists, then this message is not shown, because the system automatically 
loads the subprogram from mass storage. However, if a program file 
(BASIC/PROG) with this name already exists, an ERROR 68 : FILE TYPE 
error will be reported. 



The FINDPROG statement also directs all subsequent program-editing operations (like DELETE, 
LIST, etc.) to be made on this subprogram. 

You should now see something like this: 

BASIC program bytes lines allocated 

MAIN 196 9 no 

> FirstSub no 

The > points to the subprogram (or program) that will be the target of subsequent editing 
operations. After verifying that the editor is now pointed at subprogram "FirstSub", you can 
begin typing it in. 
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A Note about Naming Subprograms 

A subprogram has a name which may be up to 14 characters long, just as with line labels and 
variable names. Here are some legal subprogram names: 

PlotDATA 
InitializeDisc 
Read.DVM 
Sort_2D_array 

Because up to 14 characters are allowed for naming subprograms, it is easy and convenient 
to name subprograms in such a way as to reflect the purpose for which the subprogram was 
written. 



NOTE 

The name of the subprogram specified in FINDPROG statement is also 
the name that you must specify in the STORE statement that stores the 
subprogram in a file. Although you can use any name in the SUB heading, 
it is probably best to use the same name there, also. 



Entering a New Subprogram 

Now that you have reserved a location in memory for the subprogram, you can begin typing it 
in. Enter this example subroutine. 

100 SUB "FirstSub" 

110 DISP "This is displayed by 'FirstSub'." 

120 DISP 

130 SUBEMD 

Note that the first line must contain the heading declaration SUB followed by the subprogram 
name. Note also that line numbers in the subprogram are completely independent of line numbers 
in the main program, so the subprogram can start with any (valid) line number. 
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Storing the Subprogram 

Use the STORE command to store a copy of the subprogram in a file. You will need to specify 
the same name that you specified in the FINDPROG statement that pointed the editor at this 
subprogram. In this example, you would type: 

STORE "FirstSub" 

Only the first 14 characters of the file name are used if you specify one longer than 14 characters. 

Now that the subprogram is stored, you can easily call it from any program (or from any other 
subprogram, for that matter). 



NOTE 

Do not use the SAVE command to record a subprogram, because SAVE 
does not put the subprogram in the proper file type (BASIC/SUBP) for 
subsequent FINDPROG and CALL statements. 



Entering and Storing the Second Subprogram 

Now you are ready to perform similar steps to enter and store the second example subprogram. 
Here is another listing for your convenience. 

100 SUB "SecondSub" (Formal_param$) 

110 DISP "This is displayed by 'SecondSub'." 

120 DISP "The value sent to me is '" ; Formal_param$ ; " ' . " 

130 DISP 

140 SUBEND 

Repeat the procedure you used to enter and store the first subprogram. 



6-16 User- Defined Functions and Subprograms 



Running the Program 

Now that you have entered the program and both subprograms, you are ready to run the 
program. Execute: 

RUN 

You should get results like these: 

This is displayed by the MAIN program. 

This is displayed by 'FirstSub' . 

This is displayed by 'SecondSub' . 

The value sent to me is 'String pass parameter' . 

This is the MAIN program again. 

Subprograms Are Automatically Loaded 

Since the subprogram in the preceding example was already in memory when the main program 
was executed, the system did not need to load it. However, if a subprogram is not in memory 
when called, then it will be automatically loaded. In order to verify that this is the case, let's first 
delete one of the subprograms. 

Deleting a Subprogram 

Use the SCRATCHSUB statement to delete a subprogram currently in your BASIC memory area. 
This example deletes subprogram FirstSub: 

SCRATCHSUB "FirstSub" 

Executing a DIRECTORY statement will now show that the subprogram is not in memory. 
DIRECTORY 

BASIC program bytes lines allocated 

> MAIN 196 9 yes 

SecondSub 156 5 yes 

If you run the program at this point, the system will automatically load the subprogram when it 
is called. 

Note that you can also execute SCRATCHSUB from a running program; see the subsequent "Mem- 
ory Management with Subprograms" section for more complete details. 
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Explicitly Loading Subprograms (For Editing) 

There are two general instances when subprograms will be loaded: 

• When a program calls it. 

• When you want to edit it. 

As mentioned previously, when a subprogram that is not currently in memory is called, the 
system automatically loads it. Thus, about the only time that you will need to explicitly load a 
subprogram is for editing purposes. 

To load a subprogram for editing purposes, merely execute a FINDPROG statement, specifying 
the subprogram name — which is also the file name. (It is possible to bring in as many 
subprograms into the computer as you like, limited only by available memory.) Let's load the 
example subprogram created in an earlier section: 

FINDPROG "FirstSub" 

Executing a DIRECTORY statement will verify that the subprogram has been loaded: 
DIRECTORY 



BASIC program 


bytes 


lines 


allocated 


MAIN 


196 


9 


yes 


SecondSub 


156 


5 


yes 


> FirstSub 


76 


4 


no 



Any subsequent LIST statements or editing operations (such as entering a line or using SCAN, 
etc.) will be performed on this subprogram. 

For further information about loading and deleting subprograms, see the subsequent section 
called "Memory Management with Subprograms." 

Now that you have the basic mechanics of entering, storing, and calling simple subprograms, 
let's look closer at some of their more powerful usages. 
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Program/Subprogram Communication 

As mentioned earlier, the two main features of subprograms that make them so powerful are as 
follows: 

• You can handle each subprogram like a separate program. 

• You can allow (or deny) a subprogram access to certain variables and values in the main 
program (or subprogram) that calls it. 

This section disusses the second feature. 

Here are the methods that a subprogram can communicate with the main program or with other 
subprograms: 

• By passing parameters (through parameter lists) 

• By sharing common variables (declared in COM statements) 

• By using system flags. 

System flags are accessible to every subprogram (and user-defined function). However, all vari- 
ables and values in the calling program that are not explicitly passed to the subprogram or in 
COM are not accessible to the subprogram. 

Passing Parameters 

The second subprogram presented earlier in this chapter showed one means of communicating 
with a subprogram. Here is the relevant statement in the main program. 

130 CALL "SecondSub" ("String pass parameter") 

The characters String pass parameter are passed to SecondSub by specifying it as a pass 
parameter (in parentheses). 

The SUB declaration in the subprogram (line 100) has a corresponding parameter — the string 
variable named Formal_param$. 

100 SUB "SecondSub" (Formal_param$) 

110 DISP "This is displayed by 'SecondSub'." 

120 DISP "The value sent to me is " ; Formal_param$ ; " ' . " 

130 SUBEND 



User-Defined Functions and Subprograms 6—19 



The subprogram has been defined to receive a string parameter from the context that calls it. 
Within the subprogram, this "local" variable will initially be assigned the value passed to it. 

Here are the lines that the subprogram displays. 

This is displayed by 'SecondSub'. 

The value sent to me is 'String pass parameter' . 

These results verify that the value specified in the CALL was the value that the subprogram 
received. Let's take a closer look at parameter lists. 

Parameter Lists 

There are two kinds of parameter lists: 

• Pass parameter lists 

• Formal parameter lists 

The calling context provides a pass parameter list. It contains values that are sent to the 
subprogram. Here is the pass parameter list used in a call to the preceding example subprogram: 

130 CALL "SecondSub" ("String pass parameter") 

Each item in this list corresponds to an item in the subprogram's formal parameter list. 

The formal parameter list is part of the subprogram's definition. It immediately follows the 
subprogram's name. Here is the formal parameter list of the preceding example subprogram: 

100 SUB "SecondSub" (Formal_param$) 

The formal parameter list serves three main purposes: 

• It tells how many values may be passed to a subprogram: the calling context can pass one 
value for every formal parameter . 

• It names the variables that the subprogram will use to store and access those values. 

• It shows the general type of each pass parameter — numeric or string. 

The general type of each pass parameter — numeric or string — must match the general type of 
the corresponding formal parameter; otherwise Error 32 : PARAM MISMATCH is reported. The 
next section provides more details on how the specific type of each parameter is declared. 



Note that the calling context may also pass fewer parameters than are declared in the formal parameter list. See the subsequent section 

called "Optional Pass Parameters." 

Note, however, that the formal parameter list does not declare the parameter's specific type — such as INTEGER for numeric parameters, 

and string length for string parameters. That subject is discussed in the subsequent section called "When Are Pass Parameter Types 

Declared?" 
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Methods of Passing Parameters 

There are two ways for the calling context to pass parameters to a subprogram: 

• By reference (or "address"). 

• By value. 

The subprogram has no control over whether its parameters are sent by value or by reference. 
That is determined by the parameters placed in the calling context's pass parameter list. 

• To pass a parameter by reference, the pass parameter list (in the calling context) must 
use a variable name for that parameter. 

• To pass a parameter by value, the pass parameter list must use an expression for that 
parameter. (Note that enclosing a variable in parentheses is sufficient to create an expres- 
sion.) 

The main difference between the two methods is that a subprogram can alter the value of 

a variable passed by reference from the calling context. The calling context actually gives the 
subprogram access to its value area (for that variable). A parameter passed by value provides 
no such access. 

Example of Passing by Reference 

This program passes a string variable and an INTEGER variable by reference: 

100 ! Pass two parameters BY REFERENCE. 

110 ! 

120 DIM String$ [30] 

130 String$="A string of thirty characters." 

140 ! 

150 INTEGER Intgr 

160 Intgr=32 

170 ! 

180 DISP "Before pass by reference:" 

190 DISP String$ , Intgr 

200 DISP 

210 CALL "ChangeParams" (StringS, Intgr) 

220 ! 

230 DISP "After pass by reference:" 

240 DISP StringS , Intgr 

250 DISP 

260 ! 

270 END 
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Here is the subprogram: 

100 SUB "ChangeParams" (Formal$,FormalN) 

110 ! 

120 DISP "At subprogram entry:" 

130 DISP Formal$,FormalN 

140 DISP 

150 ! 

160 Formal$=" Short string." 

170 FormalN=FormalN*2 

180 ! 

190 DISP "At subprogram exit : " 

200 DISP Formal$,FormalN 

210 DISP 

220 ! 

230 SUBEND 

Here are the results of running the program. 

Before pass by reference: 

A string of thirty characters. 32 

At subprogram entry: 

A string of thirty characters. 32 

At subprogram exit : 
Short string. 64 

After pass by reference: 
Short string. 64 

The program passes the variables String$ and Intgr to the subprogram by reference. The 
subprogram accesses them as Formal$ and FormalN, but it is actually accessing the main program 
variables String$ and Intgr. When the subprogram changes the value of these variables, the 
change is made directly to the main program's String$ and Intgr variables. 
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Example of Passing by Value 

This program passes a string value and an INTEGER variable by value: 

100 ! Pass two parameters BY VALUE. 

110 ! 

120 DIM String$[30] 

130 String$="A string of thirty characters." 

140 ! 

150 INTEGER Intgr 

160 Intgr=32 

170 ! 

180 DISP "Before pass by value:" 

190 DISP String$ , Intgr 

200 DISP 

210 CALL "ChangeParams" ("String value. ", (Intgr)) 

220 ! 

230 DISP "After pass by value:" 

240 DISP String$ , Intgr 

250 DISP 

260 ! 

270 END 

Note that the program calls the same subprogram as in the last example. Here are the results 
of running the program. 

Before pass by value: 

A string of thirty characters. 32 

At subprogram entry: 
String value. 32 

At subprogram exit : 
Short string. 64 

After pass by value: 

A string of thirty characters. 32 

These parameters were passed by value, which means that the values were assigned to the 
formal parameters Formal$ and FormalN but no "addresses" of any main program variables 
were passed with the values. Thus the value of Intgr was not changed, because the subprogram 
did not have access to the variable. 
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When Are Pass Parameter Types Declared? 

As you studied the preceding examples, you may have wondered just how and when the data 
type of a subprogram's formal parameters are declared. The answer depends on how the 
parameter was passed to the subprogram: 

• If the parameter is passed by reference, then the corresponding formal parameter inherits 
information about the variable from the calling context (data type, simple or array variable, 
etc.). 

• If the parameter is passed by value, then the formal parameter has the default attributes 
for that general data type: 18 characters for strings, and REAL for numerics. 

Thus it is possible, for example, to pass an INTEGER, SHORT, or REAL variable to a subprogram 
without causing ERROR 113 : PARAM MISMATCH. (Of course, the corresponding formal parameter 
must be a numeric variable.) Here is a simple example: 

100 ! Explicitly declare an INTEGER. 

110 INTEGER Intgr ! Explicitly declared an INTEGER. 

120 Intgr=32 

130 CALL "ShowParam" (Intgr) 

140 ! 

150 ! Implicitly declare a REAL. 

160 Number=12.34 

170 CALL "ShowParam" (Number) 

180 ! 

190 END 

Here is the subprogram that it calls. 

1O0 SUB "ShowParam" (AnyNumeric) 

110 ! 

120 DISP "Value of numeric parameter ="; AnyNumeric 

130 DISP 

140 ! 

150 SUBEND 

Here are the program's results. 

Value of numeric parameter = 32 
Value of numeric parameter = 12.34 



6-24 User-Defined Functions and Subprograms 



The program first explicitly 1 declares the simple numeric variable named Intgr to be of type 
INTEGER, assigns it a value, and then passes the value by reference to the subprogram. The 
subprogram then displays the value, and returns control to the calling program. 

The program then implicitly declares the simple numeric variable named Number to be of type 
REAL, assigns it a value, and then passes the value to the subprogram by reference. The 
subprogram displays this value, and then returns control to the calling program. 

In summary, the declaration of a variable's type, whether explicit or implicit, is made in the 
defining context — the passed to a subprogram by reference, information about the variable 
(type; simple or array, and array size; etc.) is inherited by the subprogram. 

Optional Pass Parameters 

Another important feature of passing parameters is that all pass parameters are optional. 

However, the rules requiring matching of parameter types still apply. For instance, you may 
legally pass just three parameters to a subprogram that lists five formal parameters. However, 
these three pass parameters must match (in order, by type) the first three formal parameters. 
You cannot pass, for example, only the last three parameters. 

There is a standard function called NPAR which can be used inside the subprogram to find out 
how many parameters the calling context actually did pass. If no parameters are passed to the 
subprogram, NPAR will return 0. (If used inside the main program, it will also return 0.) 

The optional parameter feature is very effectively used in situations requiring external instrument 
setups. Most instruments have several different ranges, modes, settings, etc., which can be used 
depending upon the requirements of the user. Often, the user doesn't require the entire flexibility 
the instrument has to offer, and would rather use some reasonable defaults. 

Consider the HP 3437A Digital Voltmeter. Among other things, this device has two data 
formats (packed and ASCII), three trigger modes (internal, external, and hold/manual), three 
voltage ranges (0.1V, IV, and 10V), and also has programmable values for delay between 
readings, and numbers of readings taken. Naturally, the values used for the various settings will 
depend entirely upon the application for which the voltmeter is being used, but let's make some 
assumptions: 

• The values for delay and number of readings are going to be changed frequently, so they 
will not be optional parameters. 

• Of the remaining parameters, the range is most likely to be altered. 



Further details of explicit and implicit type declarations are given in the "Numeric Computation" and "String Manipulation" chapters. 

User-Defined Functions and Subprograms 6-25 



A reasonable setup routine for the voltmeter might look like this: 



2000 
2010 
2020 
2030 
2040 
2050 
2060 
2070 
2080 
2090 
2100 
2110 
2120 
2130 
2140 
2150 
2160 
2170 
2180 
2190 
2200 
2210 
2220 
2230 
2240 
2250 



SUB "DVM_Setup" (Dvm .Readings, Delay ,PRange,PTrigr .PFormat) 
Assume that AT LEAST 3 parameters will always be passed. 

(Re) set defaults. 
Range=2 ! 1-Volt range. 
Trigr=l ! Internal trigger. 
Format=l ! ASCII format. 
! 

IF NPAR<4 THEN GOTO Build.Strings 
Range=PRange 
! 

IF NPAR<5 THEN GOTO Build.Strings 
Trigr=PTrigr 
! 

IF NPAR<6 THEN GOTO Build.Strings 
F ormat =PF ormat 
i 

Build.Strings: Rdngs$="N"&VAL$ (Readings) &"S" 
Delay$="D"&VAL$(Delay)&"S" 
Range$="R"&VAL$ (Range) 
Trigr$="T"&VAL$ (Trigr) 
Format $="F"&VAL$ (Format) 
! 

OUTPUT Dvm ; Rdngs$&Delay$&Range$&Trigr$&Format$ 
! 

SUBEND 



The subprogram defines defaults for voltmeter range, trigger, and format modes (lines 2040 
through 2060) for the instances when these parameters are not passed to it. If, for instance, a 
value for range is passed (through PRange), then the subprogram assigns this value to the local 
variable named Range. 



Legal invocations of the Setup.dvm subprogram are as follows: 



570 CALL "DVM.Setup" 
630 CALL "DVM.Setup" 
850 CALL "DVM.Setup" 
950 CALL "DVM.Setup" 



(Dvm, 100,0.001) ! 
(Dvm, 500, 0.05, 3) ! 
(Dvm, 50, 0.005, 1,2) ! 
(Dvm, 50, 0.005, 1,2, 2) 



Default Range, Trigr, Format 
Default Trigr , Format . 
Default Format. 
Explicitly define all params. 
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Using COM Variables 

Since we've discussed parameter lists in detail, let's turn now to the second method a subprogram 
has of communicating with the main program or with other subprograms — using COM variables 1 . 

Here is an example of a valid COM declaration: 

10 OPTION BASE 1 

20 COM Array (15) .INTEGER, CMin,CMax,Pile_status$ [20] .Tolerance 

The following COM declaration would be legal in a subprogram (or in a chained program that is 
to keep the same COM structure): 

100 OPTION BASE 1 

110 COM Z (15) .INTEGER, MinC , MaxC , St$ [20] .ErrorMax 

As in parameter lists, COM variables are matched by position and type, not by variable names. 
Note that the OPTION BASE must match, and that COM statements must be placed following the 
OPTION BASE statement and before any other reference to the variable. 

Note also that, from left to right in a given COM list, all variables following a numeric data-type 
declaration keyword have that numeric type until another numeric declaration keyword appears 
in the list. In the above examples, both CMin and CMax (MinC and MaxC) are INTEGERS, but 
Tolerance (ErrorMax) is a REAL variable; this effect is due to the fact that Pile_status$ (St$) is a 
string, which causes the following numeric variable to be of the default numeric type REAL. 

Consider the following COM declaration: 

10 COM INTEGER Range , Format , N , REAL Delay ,Lastdata(40) , Status$ [20] 

The following COM block matches the preceding COM block explicitly and is legal: 
110 COM INTEGER Range . Format . N , REAL Delay ,Lastdata(40) ,Status$[20] 



Note that COM variables can also be used for program-to-program communications when chaining programs; however, COM cannot be 
used within a user-defined function. See the chapter called "Program Structure and Flow" for a description of chaining. The subsequent 
section of this chapter called "Passing Flags to Chained Programs" describes using COM for program-to-program communications during 
chaining. 
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The following COM declaration within a different subprogram matches the preceding COM statement 
and is also legal. (Even though some variables' names have been changed, the order and number 
of variables and their types are the same). 

110 COM INTEGER R.F.N.REAL D,L(40) ,S$ [20] 

The following declaration is illegal, since it uses explicit size specifications on the array and 
string which do not match the original definition (line 10). 

120 COM INTEGER Range , Format , N , REAL Delay ,Lastdata(30) ,Status$[15] 

The following declaration is also illegal, since it violates the types set forth by the defining block 
(here Range, Format, and N are implicitly declared to be of type REAL). 

120 COM Range, Format ,N, REAL Delay ,Lastdata(40) ,Status$[20] 

COM Characteristics 

There are several characteristics of COM variables which distinguish them from parameter lists as 
a means of communications between contexts. 

COM survives pre-run 1 . In general, all numeric variables are assigned values of and strings 
are assigned the null string by executing RUN or INIT, or upon entering a subprogram; this is 
also true of COM the first time RUN or INIT is executed. However, after COM variables are defined, 
they retain their values until one of the following conditions occurs: 

• SCRATCH is executed. 

• A COM statement is modified. 

• LOAD or CHAIN loads a new program which has a COM structure that doesn't match the 
existing COM structure (which includes programs that don't declare any COM at all). 

COM blocks can be arbitrarily large. One limitation on parameter lists (both pass and formal 
parameter lists) is that they must fit into a single program line along with such things as the line 
number, possibly a line label, and the subprogram header. Depending upon the situation, this 
can impose a restriction on the size of your parameter lists. 

COM blocks can take as many statements as necessary. All COM statements within a context 
are part of the definition of that context's COM structure. COM statements can be interwoven with 
other statements, though this is considered sloppy practice. 



Pre-run is described in the section called "A Closer Look at Program Execution" in the "Program Structure and Flow" chapter. 
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COM blocks can be used for communicating between contexts that do not invoke each 
other. Information such as modes and states can be an integral part of communicating between 
contexts, even though those contexts don't explicitly call each other. For instance, one routine 
might be responsible for setting the voltage range on a voltmeter, while another routine which 
may need to know what the current voltage range is in order to set up the scale on a graph 
properly. (Technical BASIC also has system flags which you can use for this purpose. See the 
subsequent section of this chapter called "Using System Flags" for details.) 

COM blocks can be used to communicate between subprograms that are not in memory 
simultaneously. Similar to the case above, subprograms can communicate with each other 
through COM blocks even though combinations of CALL and SCRATCHSUB may preclude their 
simultaneous presence in memory. 

COM blocks can be used to retain the value of "local" variables between subprogram calls. 

In general, the variables used by a subprogram are discarded when the subprogram is exited. 
However, there are situations where it might be useful for a subprogram to "remember" a value. 
A machine which tests capacitors in an incoming inspection department may require calibration 
after every 100 tests are performed. If the subprogram which does the testing has a way to 
count how many tests it has already performed (using a COM variable), then this task can be 
left to the testing routine, simplifying the rest of the system. 

COM blocks allow subprograms to share data without the intervention of the main program. 

Subprogram libraries may consist of elaborate relationships of both programs and data structures. 
In many cases, a major portion of the data structures are only used for support of the task being 
performed, rather than being integral to the task itself. Thus the main program does not need 
to declare the supportive data structures. 

An example of this situation might include data base management libraries: hashing tables may 
need to be maintained for accessing data quickly. Three dimensional graphics libraries are 
another example: window, viewport, and clip information need to be kept, as well as object 
definitions and related transformations. 
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Using System Flags 

System flags are the third method for communications between a main program and its subpro- 
grams (and also subsequently chained programs). In programming, the term "flag" denotes an 
indicator or reminder. Flags are used flags for various functions, such as in determining when to 
branch or in calculating the value to be assigned to a variable. For instance, you can use a flag 
to keep track of which mode a routine is operating in and thus whether to call a subroutine: 

200 InsertMode=l ! Set the flag. 



300 IF InsertMode THEN GOSUB Insert ! Branch if flag set. 

With Technical BASIC, you can also resident flags (numbered 1 through 64). Here is an example 
analogous to the preceding one: 

100 InsertFlag=10 ! Specify system flag used for Insert Mode. 



200 SFLAG(InsertFlag) ! Set the flag. 

300 IF FLAG(InsertFlag) THEN GOSUB Insert ! Branch if flag set. 
If the FLAG function returns a 1, then the program branches to the subroutine called Insert. 

General System Flag Features 

Each of 64 flags which can be individually set and cleared. When set, a flag contains a value 
of 1. When cleared, its value returns to 0. They are initially cleared upon entering the BASIC 
system. 

The normal scope of system flags is a program and its subprogram(s), since executing a CHAIN 
statement clears all flags. However, you can store the flags in COM, as discussed later in this 
section, to pass them to chained programs. 

While flags are usually used within running programs, they can also be set, tested, and cleared 
from the keyboard. 
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Setting Flags 

Individual flags are set by using the SFLAG statement. For instance, this statement sets system 
flag 32 (to 1). 

SFLAG 32 

Note that this statement may be used within a program: 

100 LET MinFlag=MIN(Nl,N2) 
110 SFLAG MinFlag 

Reading Flags 

The following function call determines the current setting of system flag 32: 

FLAG (32) 

If the flag is set, then this function call returns the numeric value 1; if currently clear, then is 
returned. 

Clearing Flags 

The following statement clears system flag 32: 

CFLAG 32 

Executing this function call now returns a numeric value of 0: 

FLAG (32) 


The CFLAG statement clears one flag at a time, whereas executing INIT, RUN, or CHAIN clears 
all 64 flags. Note also that a parameter less than 1 or greater than 64 will generate an error 
report. Also, both CFLAG and SFLAG rounds flag numbers containing fractional parts. 

Accessing System Flags as a String 

The concise way to set or clear each of the 64 flags in a single statement is to use this syntax 
of the SFLAG command: 

SFLAG FlagString8$ 

This FlagString8$ expression may contain up to 8 characters (64 bits) of information. The value 
of the characters in the string determine whether flags are set or cleared: flags that correspond 
to 1 bits (in the binary representation of the character) are set, and flags that correspond to 
bits are cleared. 
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For example, if you were to set the flags using the character string "ABCD0123", you could 
determine the resultant bit patterns (and corresponding flag settings) using the following method: 

Table 6-1. FLAGS and BIT Patterns 



Character 


Decimal Code 


Binary Code 


String Position 


A 


65 


01000001 


1 


B 


66 


01000010 


2 


C 


67 


01000011 


3 


D 


68 


01000100 


4 





48 


00110000 


5 


1 


49 


00110001 


6 


2 


50 


00110010 


7 


3 


51 


00110011 


8 



Using l's and 0's, the following diagram specifies the settings of flags 1 through 64 from left to 
right, respectively; the 64 bits (flags) have been grouped into eight characters (or bytes). 



(01000001) 
1 

(00110000) 
5 



(01000010) 
2 

(00110001) 
6 



(01000011) 
3 

(00110010) 
7 



(01000100) 
4 

(00110011) 



You can use either of the following programs to set the flags shown in the above diagram: 



10 SFLAG "ABCD0123" 
20 END 



10 FlagString8$=CHR$ (65) &CHR$ (66) &CHR$ (67) &CHR$ (68) 

20 FlagString8$=FlagString8$&CHR$ (48) &CHR$ (49) &CHR$ (50) &CHR$ (51) 

30 SFLAG FlagString8$ 

40 END 

SFLAG truncates strings longer than eight characters at the eighth character. Strings shorter than 
eight characters are filled with "null" control characters, CHR$(0); consequently, all flags after 
the last one are set to (cleared). 
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Passing Flags to Chained Programs 

If you desire to pass flags from program to program as you chain them, then you will need to 
use the COM statement, because the CHAIN statement clears all flags. The following segment of 
a program is an example of how flags can be passed to the next program when chaining. 

100 COM SysFlags$[8] 



790 SysFlags$=FLAG$ 

800 CHAIN "NextProg" ! Must have identical COM structure. 

This passes all 64 flags to the chained program through the "common" variable storage area. 
Note that the chained program must have a matching COM structure, or the existing COM will 
be destroyed by the new COM, and the new COM variables will be initialized implicitly: numeric 
variables will be set to 0, and string variables will be set to the null string. 
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Memory Management with Subprograms 

The CALL and* SCRATCHSUB statements allow for subprogram overlays to re-use the same memory 
space. This is useful for programs which are large enough that they won't all fit into memory at 
once, whether the programs themselves are too numerous and/or too large, or whether variables 
and arrays use enormous amounts of space. 

The SCRATCHSUB statement allows you two options: 

• You can specify the name of a single subprogram to be deleted from memory. 

SCRATCHSUB "Sort" 

• You can specify a subprogram and delete that subprogram and all subprograms in memory 
from that point on. 

SCRATCHSUB "Control.valves" TO END 

If the system tries to delete a subprogram which is not currently in memory, no error will be 
reported. 

A subprogram can only be deleted if it is not currently "active.". This means that: 

• A subprogram can not delete itself. 

• A subprogram cannot delete the subprogram that called it. (Otherwise it wouldn't have 
any place to go when the SUBEND or SUBEXIT statement was encountered!) 

Between the time that a subprogram is entered and the time it is exited, the Technical BASIC 
system keeps track of an "activation record" for that subprogram. Thus if the subprogram calls 
a subprogram which calls a subprogram, and so forth, then none of the subsequently called 
subprograms can delete the original one (or any of the ones in between), because the system 
knows from the activation record that eventually the program will need to return to the calling 
context. 
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Context Switching 



As mentioned in the introduction to this chapter, a subprogram has its own context, or state, 
which is distinct from a main program and all other subprograms. Consequently there are 
many things, such as line numbers, line labels, and variables, which are "local" to programs and 
subprograms. On the other hand, there are several modes, flags, and so forth, that are "global" 
to programs and subprograms. This section shows what is local and what is global. 

Global Declarations 

Default lower bound OPTION BASE 1 

of array dimensions 

Trigonometric modes DEG, RAD, and GRAD 

All working directory changes MASS STORAGE IS 

All file-create operations CREATE 

System screen operations 

System printer operations 

All graphics operations 

Error reporting 

System flags 

File buffers 



CRT IS, ON CURSOR, OFF CURSOR, FLIP 
PRINTER IS, PRINT ALL, NORMAL 
PLOT, DRAW, PEN, PLOTTER IS etc. 
DEFAULT ON, DEFAULT OFF 
FLAG, SFLAG, CFLAG 
ASSIGN* 



Local Declarations 

Error trapping 
Softkey interrupts 
Keystroke trapping 
Timeout interrupts 
Timer interrupts 



ON ERROR GOTO/GOSUB, OFF ERROR 

ON KEY# . . GOTO/GOSUB, OFF KEY# 

ON KYBD GOTO/GOSUB, OFF KYBD 

ON TIMEOUT. . .GOTO/GOSUB, OFF TIMEOUT 

ON TIMER#. . .GOTO/GOSUB, OFF TIMER* 



For further details on each statement, see the Technical BASIC Language Reference. 



Since OPTION BASE is global, attempting to use different OPTION BASE statements in program and subprograms will produce errors. 
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Notes 
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Error Handling 



7 



Introduction 

Most programs are initially subject to errors at run time, even if all the typographical/syntactical 
errors have been shaken out while entering the program into the computer. There are three 
general courses of action to take with respect to run-time errors: 

1. Try to prevent the error from happening in the first place. 

2. Once an error occurs, try to recover from it and continue execution. 

3. Do nothing — let the program "roll over and die" if an error occurs. 

The last alternative, which may seem frivolous at first glance, is certainly the easiest to implement. 
Furthermore, the friendly nature of the HP-UX Technical BASIC system makes this a feasible 
choice — if the person running the program is a programmer, or better yet is the person who 
wrote the program. Upon encountering a run-time error, the BASIC system pauses program 
execution and displays a message giving the error number 1 and the line in which the error 
happened. The operator /programmer can then examine the program in light of this information 
and fix things up. 

On the other hand, if the the person running the program did not write it, then the first two 
approaches above should be used. The program should attempt to prevent errors from happening 
in the first place, and when they do occur to recover gracefully and continue running. 

Chapter Contents 

This chapter discusses the following topics: 



Tasks/Topics 


Page 


How the BASIC system handles errors 


7-2 


Anticipating operator errors 


7-3 


Checking for boundary conditions 


7-3 


Comparison errors 


7-5 


Trapping errors 


7-6 


Determining error numbers and location 


7-7 


Displaying the normal system error message 


7-8 



A complete list of error numbers and definitions is provided in the back of the HP-UX Technical BASIC Language Reference. 
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How the System Handles Errors 

The Technical BASIC system is designed to recognize a broad range of errors. For instance, if a 
program attempts to evaluate a mathematical operation whose results are not defined (such as 
division by zero), then the system will report an error condition. This section briefly describes 
how the system normally reports these errors. The subsequent sections describe how you can 
anticipate these errors and handle them from a program. 

Errors in Keyboard Calculations 

Errors encountered while you are trying to execute a command or evaluate an expression from 
the keyboard are trapped by the system. The default response of the system is to give you a 
warning. Here is an erroneous math operation: 

1/0 

Here is the system's default response to attempting the operation: 

warning 2 OVERFLOW 
1 .79769313486231e+308 

The system attempts to tell you more about the error by showing that the result is larger than it 
can represent; the value shown is the largest number that the system can handle. This is known 
as the "default value" for the out-of-range result. (There are similar errors in the range of error 
number 1 through 8.) 

If you now execute: 
DEFAULT OFF 

The system will not display the "default value" for the out-of-range math error. Here are the 
results of performing the preceding 1/0 calculation with DEFAULT OFF: 

Error 2 OVERFLOW 

The differences between DEFAULT ON and DEFAULT OFF while a program is running are much 
more significant. They are the topic of the subsequent paragraphs. 
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Run-Time Errors 

Run-time errors occur while a program is being executed. There are three ways that the BASIC 
system can handle "out-of-range" math errors: 

• Display a warning, give the default value, and continue the calculation with the default 
value. (This is the system's response with DEFAULT ON.) 

• Halt execution and display an error report. (This is the system's response with DEFAULT 
OFF.) 

• Not display the report, but pass it on to an "error handler" routine in the BASIC program. 

The next section shows how to anticipate (and thereby avoid) most errors. The section after 
that shows how to trap errors (and optionally correct them) from a running program. 



Anticipating Operator Errors 

The programmer that writes a program (hopefully) knows exactly what the program is expected 
to do and what kinds of inputs make sense for each task. Given this viewpoint, there is a strong 
tendency not to take into account the possibility that other people using the program might not 
understand the range of valid inputs. 

As a programmer who wants your programs to be reasonably reliable, you really have no 
choice but to assume that users can make mistakes that cause errors every time they have the 
opportunity to enter information. Thus, the goal is to make the program reasonably foolproof. 

Boundary Conditions 

A classic example of anticipating an operator error is the "division by zero" situation. For 
instance, suppose that an INPUT statement is used to get the value for a variable, and the 
variable is used as a divisor later in the program. If the operator should happen to enter a zero, 
accidentally or intentionally, the program crashes with an error 31. It is far better to be watching 
for an out-of-range input and respond gracefully. One method is shown in the following example. 

100 DISP "Miles traveled and total hours" @ INPUT Miles, Hours 

110 IF Hours<=0 THEN 120 ELSE 160 

120 BEEP 

130 PRINT "Improper value entered for hours." 

140 PRINT "Try again!" 

150 GOTO 100 

160 ! Input OK, so continue normally. 
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Consider another simple example of giving a user the choice of six colors for a bar graph. It 
might be preferable to have the user pick a number corresponding to the color he wished to 
choose instead of having to type in up to six characters. In this case, the program wouldn't have 
to check for each number, but rather it could use the logical comparators to check for an entire 
range: 

100 CLEAR 

110 DATA GREEN, BLUE, RED, YELLOW, PURPLE, PINK 

120 DIM Colors$(6) [6] 

130 FOR Indx=l TO 6 

140 READ Colors$(Indx) 

150 NEXT Indx 

160 FOR 1=1 TO 6 

170 PRINT USING "DD.X.K" ;I,Colors$(I) 

180 NEXT I 

190 Ask: DISP "Pick the number of a color" INPUT I 

200 IF I>=1 AND I<=6 THEN Valid.Color 

210 BEEP 

220 DISP "Invalid answer -- "; 

230 WAIT 1 

240 GOTO Ask 

250 Valid_color: ! Program continues here when input is OK. 

The above example needs a little extra safeguarding. The input variable I should be declared to 
be an INTEGER, since the only valid inputs are 1, 2, 3, 4, 5, and 6. An answer like "You have 
picked the 3.14th color listed" does not make sense. 

Here is an example that tests real number boundaries: 

7000 AskFreq: DISP "Enter the waveform's frequency (in KHz)" 

7010 INPUT Frequency 

7020 IF Frequency<=0 THEN AskFreq 

7025 ! 

7030 AskAmpl: DISP "Enter the amplitude (0-10 volts)" 

7040 INPUT Amplitude 

7050 IF Amplitude<0 OR Amplitude>10 THEN AskAmpl 

7055 ! 

7060 AskDeg: DISP "Enter the phase angle (in degrees)" 

7070 INPUT Angle 

7080 IF Angle<0 OR Angle>180 THEN AskDeg 
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REAL Numbers and Comparisons 

A word of caution is in order about the use of the = comparison operator in conjunction with real 
numbers — numbers of type REAL and SHORT. Numbers on this computer are stored in a binary 
form, which means that the information stored is not guaranteed to be an exact representation 
of a decimal number — even though it will be really close! What this means is that a program 
should not use the = operator for comparing real numbers. The comparison will yield a 'false' 
or '0' value if the two are different by even one bit, even though the two numbers might really 
be equal for all practical purposes. 

There are two ways around this problem. The first is to try to state the comparison in terms of 
the <= or >= comparators. However, if it is absolutely necessary to do an equality comparison 
with a pair of real numbers, then a second method must be used. This method involves picking 
an error tolerance for how close to being equal the two numbers can be to satisfy the test. 

Real number line < ► 

XI X2 



So if the difference between two real numbers XI and X2 is less than or equal to a tolerance 
6, we'll say that XI and X2 are "equal" to each other for all practical purposes. The value of 
6 will depend upon the application, and must be chosen with care. 

For an example, assume that we've picked a tolerance of 1E-12 for comparing two real numbers 
for equality. The proper way to compare the two numbers would be: 

950 IF ABS(X1-X2)<=1E-12 THEN Numbers_equal 
960 ! Otherwise they're not equal 
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Trapping Errors 

Despite your best efforts at screening the operator's inputs to avoid errors, errors will still 
occasionally happen. It is still possible to recover from run-time errors, provided you predict the 
places where errors are most likely to happen. 

Setting Up the Error Branch 

The ON ERROR command sets up a branch which will be initiated any time a recoverable error is 
encountered at run time. The branching action taken may be either GOTO or GOSUB . GOTO and 
GOSUB are purely local in scope — that is, they are active only within the context in which the 
ON ERROR is declared, not in any subprogram or user-defined function. 

Here is a simplistic example of using the ON ERROR statement: 

10 ON ERROR GOTO Trap 

20 A=l/0 

30 DISP "DONE" ! This and next line not executed. 

40 STOP 

50 ! 

60 Trap: DISP "ERROR: Division by 0" 

70 END 

Executing an ON ERROR statement directs the BASIC system not to report subsequent errors; 
instead, the system is to initiate a branch, GOTO or GOSUB, to the specified location in the program. 
The BASIC statements at that location can then handle the error. 

When line 20 is executed, an error is detected and the system executes the GOTO Trap specified 
in the ON ERROR statement. For simplicity, the Trap routine merely prints the corresponding 
message and ends the program. (Note that lines 30 and 40 are not executed.) 
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Determining Error Number and Location 

In the preceding example, it was assumed that the only error that could be produced was error 
2 — the division by in line 20. However, it is rarely the case that you know which error has 
happened or where it has happened. A more general error-trapping routine would determine 
which error happened and where it happened. 

ERRN is a function which returns the error number which caused the branch to be taken. ERRN 
is a global function; it can be used in the main program or in any subprogram to determine the 
number of the most recent error. Here are a couple of simple examples: 

100 DISP "Error number ";ERRN;" has occurred." 
740 IF ERRN=18 THEN GOTO String.Error 

ERRL is a function which is used to find the line in which the error was encountered. ERRL is a 
boolean function. The program passes it a line identifier (either line number or label), and the 
function returns either a 1 or a — depending upon whether or not the specified identifier 
indicates the line which caused the error, respectively. ERRL is also a global function. 

1140 IF ERRL (710) THEN DISP "The error occurred in line 710." 
910 IF ERRL (Compute) THEN Fix.compute 

Error Subroutines 

The ON ERROR GOSUB statement sets up and enables a branch to the error service routine which 
will RETURN execution to the line following the one that caused the error. 

100 Radical=B*B-4*A*C 

110 lmaginary=0 

120 ON ERROR GOSUB Esr 

130 Partial=SQR (Radical) 

140 IF Imaginary THEN Partial=SQR(Radical) ! Re-calculate. 

150 OFF ERROR 



350 Esr: IF ERRN=10 THEN Imagin ELSE OtherError 

360 Imagin: Imaginary=l Set flag. 

370 Radical=ABS (Radical) ! Make arg. positive. 

380 GOTO Endlf 

390 OtherError: BEEP 

400 BEEP 

410 DISP "Unexpected Error (";ERRN;")" 

420 PAUSE 

430 Endlf: RETURN 
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Displaying the System Error Message 

When you trap an error programmatically, you disable the system's normal error reporting 
mechanism. The system assumes that you want to handle errors yourself, which may include 
correcting the problem and then re-trying the operation. However, there are certain times when 
you do not (or cannot) fix the error. In some of these cases, you may want to report the error 
to the computer operator, who may just note the error or try to correct it. 

The ERRM statement displays the "error message" that would have been reported by the system 
when the last error occurred. Here is an example of using this feature. 

100 IF StillNotFixed THEN ERRM 
110 RETURN 
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Introduction 

Naturally, the ideal way to develop a program is to design and implement it correctly the first 
time and not have to debug it at all. This is a worthwhile goal, and most programmers strive 
constantly to achieve it. Hopefully, the techniques discussed in preceding chapters will help you 
get a little closer to this goal. 

However, no matter how good a programmer you are or how much time you have spent designing 
your programs, most programs will at one time or another be plagued with a "bug" — a bug is 
present whenever the program does not do what the user expects it to do. 

You may usually think of a bug as something that generates an error condition, such as ERROR 
68 FILE TYPE. However, a bug doesn't always inform you of its existence. In fact, the most 
insidious bugs cause your program to give a wrong answer without any indication that a bug 
even exists. This chapter deals with the methods available with Technical BASIC to diagnose 
problems in both logic and semantics. 

The problem of debugging a program is distinct from the issues raised in the "Error Handling" 
chapter. That chapter was based on the premise that the programmer is already satisfied that 
the program works as it should, and that the next step is to make it as foolproof as possible. 
That assumption could be construed as putting the cart before the horse — before you can 
make a program foolproof, you must get it to run correctly in the first place. 
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Chapter Contents 

This chapter discusses the following topics: 



Tasks/ Topics 


Page 


Whence cometh bugs? 


8-3 


Methods of debugging programs 


8-4 


Code walk-throughs 


8-4 


Printing all program results 


8-5 


Cross references 


8-5 


Tracing program flow 


8-7 


Setting breakpoints 


8-13 


Checking variables' contents from the keyboard 


8-14 


Continuing program execution. 


8-15 


Single-stepping a program 


8-16 


Software testing. 


8-17 
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Whence Cometh Bugs? 

As mentioned in the introduction of this chapter, a bug 1 is present when the program does not 
do what the user reasonably expects it to do. Generally, this definition involves two main steps: 

• Determining (or setting) the user's expectations. 

• Making sure that the program actually does what is expected. 

This chapter discusses getting your program to do what is expected. Determining and setting 
users' expectations are discussed in the chapter called "Communicating with the Operator." 

The following two topics are discussed, with the primary focus on the second one: 

• Methods of designing programs so that they do what you want them to do. 

• Methods of checking to see that part(s) of a program are doing what you want. 

A Model of the Software Development Process 

In order to find places where bugs originate, let's take a brief look back at the steps of the 
software design process shown in the "Program Development" chapter. 

1. Understand and describe the problem. 

2. Outline a solution. 

3. Design algorithms and data structures, and then refine. 

4. Translate the data structure and algorithms into BASIC code. 

5. Debug and test the program. 

6. Document and support the program. 

Note that most of these steps somehow involve either the communication or translation of infor- 
mation. For instance, step 1 involves translating the user's needs into a set of "requirements", 
while step 4 involves translating the algorithms data structures into a set of programming lan- 
guage statements. 

This translation process is one of the largest sources of bugs. It is here that you should begin 
debugging programs, because many errors in the program are only manifestations of these 
problems. 



For an excellent treatise on the origin and extermination of bugs, see Software Reliability by Glenford J. Meyers, John Wiley and Sons, 
New York, 1976. 
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Methods of Debugging Programs 

Now that you have at least an inkling of where bugs originate, you are better prepared to find 
them in your programs. This section describes several methods of ridding your programs of 
these annoying little creatures. 

Here are the general methods discussed in the remainder of this chapter: 

• Algorithm and code walk-throughs 

• Cross references 

• Tracing program flow 

• Setting breakpoints 

• Examining variables' contents from the keyboard 

• Single-stepping the program 

Walk-Throughs 

There are generally two times when you can walk through a program: 

• Before it is coded. 

• After it is coded. 

In general, the sooner you find a bug, the less it costs to fix it. 

Algorithm Walk-Throughs 

After developing an algorithm (and before coding it), you should walk through it. This walk- 
through is especially useful in checking whether you have properly translated the problem de- 
scription into the outline and then into the algorithms and data structures. 

You will perform the walk-through by acting as if you were the computer executing the algorithm 
on some actual data. At this point, you should walk through the algorithms with those program- 
mers whose algorithms will be interacting with yours. It is also a good idea to include at least 
one programmer who is not involved with the project in this exercise. 

You may also want to use specific test data (with known results) in this phase. 

BASIC Code Walk-Throughs 

Once you have coded your program, you should perform the exercise of walking through it to 
verify again that it is going to do what you want it to do. This walk through checks to see 
whether you have correctly translated the algorithms and data structures into program code. 
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Printed Records of Debugging 

When using the techniques presented in the remainder of this chapter, you will often find that 
you want to get printed records of what has happened. Normally, the cross-reference and tracing 
statements direct information to the current CRT IS device. However, you can use the PRINT 
ALL statement to direct the system to duplicate these messages on a printer, or you can specify 
another CRT IS device. For details of using printers and displays with your particular system, 
see the Getting Started Guide for your HP-UX Technical BASIC system. 

To return to sending the information only to the display, use the NORMAL statement. 

Cross References 

A cross reference is a list of this information: 

• Where variables are used in the program. 

• Where line numbers (and labels) are referenced by GOTO and GOSUB statements. 

This section explains how to obtain and interpret cross references. 

The XREF statement is programmable as well as executable from the keyboard. It provides 
a cross-reference table of program line numbers, line labels, and user-defined functions in the 
program (or subprogram) currently in memory. 

Where Are Variables Used? 

XREF V displays a cross-reference table of all the variable and user-defined functions in the current 
program (or subprogram). It is very handy in finding such subtle errors as misspelled variable 
names. 

Test the XREF V command out by entering the following program: 

10 OPTION BASE 1 

20 DIM SArray$(l)[5] 

30 SArray$(l) = "Codes" 

40 DISP "SArray$(l) = ";SAray$(D 

50 END 

Next, execute this statement: 
XREF V 



Debugging Programs 8-5 



The resulting display looks like this: 

Variable Diml Dim2 Maxl Type References 

SArray$ 1 5 string 20 30 40 

. . .end of xrefv 

The listing makes it easier to see that there are two variables, one of which is merely a misspelled 
version of the other. 

Here is what information each column contains: 

Variable the name of the variable or user-defined function. 

Diml the upper bound of the first subscript in an array variable (left blank if the variable 

is not an array). 

Dim2 the upper bound of the second subscript in an array variable (also left blank if 

the variable is not an array, or is an array with only one subscript). 

Maxl the maximum length of a string variable (left blank if the variable is not a string). 

Type INTEGER, REAL, SHORT, array, or string. 

References lines referencing the variable or user-defined function, including function defi- 
nitions (DEF FN. . .), function value assignments (FN. . . = . . .), and function calls 
(FN...). 

Where Are Program Lines Referenced? 

XREF L generates an entry in the line cross-reference table whenever a line number or line label 
is referenced. To test the XREF L command, enter the following program: 

10 X=10 

20 Y=20 

30 IF X=10 THEN GOTO 50 

40 Total=X+Y 

50 IF Total > 300 THEN Finish 

60 DISP "Total = "; Total 

70 Finish: END 

Next, execute this command: 
XREF L 
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The resulting table looks like this on your display: 
Line Cross Reference Table 

50 occurs on 30 

70 Finish: occurs on 50 

. . . end of xref 1 

Line numbers on the left of the display show a line that is referenced (such as with a GOTO or 
GOSUB). Line numbers on the right side of the display show where the reference occurred. In 
this example, a reference to line 50 occurs on line 30 (in the GOTO statement). A reference to 
line label Finish (line number 70) occurs on line 50 (also in a GOTO). 

Program Traces 

The Technical BASIC system provides means of tracing the following events: 

• A branch in the linear flow, such as when a GOTO or GOSUB is executed. 

• An assignment to a variable. 

• All program flow (including flow of control from one line to the next) and all variable 
assignments. 
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Tracing Branches 

For this section, you will be tracing bugs in the following segment of code: 

100 DIM Arg$[100] ,Result$ [100] 

110 INTEGER BeginPos.EndPos 

120 ! 

130 Arg$=" Text " 

140 DISP ,, Arg$=(";Arg$;") " , "LEN=" ;LEN(Arg$) 

150 G0SUB Trim 

160 DISP "Result$=(" ;Result$; n ) " , "LEN=" ;LEN(Result$) 

170 ! 

180 STOP 

200 ! Given string in Arg$, this subroutine 
210 ! trims leading and trailing blanks . 
220 ! Trimmed string is returned in Result$ . 

240 Trim: 

250 BeginPos=0 

260 TrimFront: BeginPos=BeginPos+l 

270 IF BeginPos>LEN(Arg$) THEN Result$="" 9 RETURN 

280 IF Arg$[BeginPos,BeginPos]=" " THEN TrimFront 

290 ! 

300 EndPos=LEN(Arg$)+l 

310 TrimEnd: EndPos=EndPos-l 

320 IF Arg$[EndPos,EndPos]=" " THEN TrimEnd 

330 ! 

340 Result$=Arg$ [BeginPos , EndPos] 

350 ! 

360 RETURN 

Here are the results of running the program without tracing. 

Arg$=( Text ) LEN= 8 

Result$=(Text) LEN= 4 

Here are the results of executing a TRACE statement and then running the program. 

Arg$=( Text ) LEN= 8 
Trace line 150 to 240 
Trace line 280 to 260 
Trace line 280 to 260 
Trace line 320 to 310 
Trace line 320 to 310 
Trace line 360 to 160 
Result$=(Text) LEN= 4 
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As you can see, only the branches (from otherwise linear program flow) are shown on the TRACE 
listing. Note also that the program's output also appears on the screen. 

You can also use TRACE statements in a program to enable tracing for only selected portions of 
the program. For instance, insert these lines into the preceding program: 

255 TRACE 

285 NORMAL 

Now execute: 

NORMAL 
to disable the TRACE enabled earlier. 

Here are the corresponding results of running the program. 

Arg$=( Text ) LEN= 8 

Trace line 280 to 260 
Trace line 280 to 260 
Result$=(Text) LEN= 4 

Note that TRACE also shows when a subprogram is called. Here is a typical display: 
Entering subprogram SUB_la 

The trace also shows when the subprogram is exited: 
Leaving subprogram SUB_la 

However, note that TRACE in this case is not enabled while in the subprogram. To do that, you 
will need to store a TRACE statement in a line that will be executed when the subprogram is 
called. 

When tracing user-defined functions, only the line number is shown, which is the same as with 
normal branches. 
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Tracing Variable Assignments 

You can use the TRACE VAR statement to display a message when a variable is assigned a value. 

Using the preceding example program, trace the variable named BeginPos. (If you inserted the 
TRACE and NORMAL statements on lines 255 and 285, respectively, you may want to delete them 
now; if so, then you will also have to execute IN IT before executing the TRACE VAR statement.) 

TRACE VAR BeginPos 
RUN 

Here are the results: 

Arg$=( Text ) LEN= 8 
Trace line 250 BeginPos=0 
Trace line 260 BeginPos=l 
Trace line 260 BeginPos=2 
Trace line 260 BeginPos=3 
Result$=(Text) LEN= 4 

As the variable being traced is assigned values, the trace shows the line number where the 
assignment is made. For numeric variables, the trace also shows the value assigned to the 
variable. For string variables, the value assigned to the variable is not shown. For instance, here 
is a trace of a string variable. (Note that the tracing of the variable named BeginPos is disabled 
with the NORMAL statement.) 

NORMAL 

TRACE VAR Arg$ 

RUN 

Tracing line 130 Arg$ 
Arg$=( Text ) LEN= 8 
Result$=(Text) LEN= 4 

As with other TRACE statements, TRACE VAR can be executed from a program or from the 
keyboard. 

If you need to trace variables in subprograms, you will need to put a TRACE VAR statement on a 
line of the subprogram that will be executed when the subprogram is called. 



NOTE 

The TRACE VAR statement does not trace variables in user-defined func- 
tions. 
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Tracing Ail Flow and Variables 

When the TRACE ALL statement is executed, it causes the system to issue a message prior to 
executing every line, not just those where branches occur. This shows the order in which all 
statements were executed. 

Here is a long, boring TRACE ALL of the example program shown in the preceding sections: 

Trace line 100 to 110 
Trace line 110 to 120 
Trace line 120 to 130 
Tracing line 130 Arg$ 
Trace line 130 to 140 
Arg$=( Text ) LEN= 8 
Trace line 140 to 150 
Trace line 150 to 240 
Trace line 240 to 250 
Trace line 250 BeginPos=0 
Trace line 250 to 260 
Trace line 260 BeginPos=l 
Trace line 260 to 270 
Trace line 270 to 280 
Trace line 280 to 260 
Trace line 260 BeginPos=2 
Trace line 260 to 270 
Trace line 270 to 280 
Trace line 280 to 260 
Trace line 260 BeginPos=3 
Trace line 260 to 270 
Trace line 270 to 280 
Trace line 280 to 290 
Trace line 290 to 300 
Trace line 300 BeginPos=9 
Trace line 300 to 310 
Trace line 310 BeginPos=8 
Trace line 310 to 320 
Trace line 320 to 310 
Trace line 310 BeginPos=7 
Trace line 310 to 320 
Trace line 320 to 310 
Trace line 310 BeginPos=6 
Trace line 310 to 320 
Trace line 320 to 330 
Trace line 330 to 340 
Tracing line 340 Result$ 
Trace line 340 to 350 
Trace line 350 to 360 
Trace line 360 to 160 
Result$=(Text) LEN= 4 
Trace line 160 to 170 
Trace line 170 to 180 
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If you have a large program, you will probably not want to perform a TRACE ALL of the whole 
thing. You can insert a program line containing TRACE ALL at the beginning of where you want 
to enable tracing, and insert a line containing NORMAL where you want to disable it. 

If you need to enable TRACE ALL in subprograms, you will need to put a TRACE ALL statement 
on a line of the subprogram that will be executed when the subprogram is called. 



NOTE 

The TRACE ALL statement does not trace either line numbers or variables 
in user-defined functions. 



Returning to Normal Execution 

NORMAL cancels the effects of any active TRACE, TRACE VAR, or TRACE ALL statements. It also 
disables PRINT ALL mode. The NORMAL statement may be executed either from the program or 
from the keyboard. 

Pausing Program Execution 

On most consoles and terminals, you can pause (temporarily halt) program execution. You can 
use [ CTRL ] - j C | providing it has been defined as the interrupt key. See the section "Testing for 
the PAUSE Capabilities" of the "Running Programs" chapter of the HP-UX Technical BASIC 
Getting Started Guide for details. This is a rather crude way of debugging, since it does not 
allow you to determine which program line will be executed next. The next section describes a 
better way to debug using breakpoints. 
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Setting Breakpoints with PAUSE 

A breakpoint is a point in the program where execution is halted. With Technical BASIC, you 
can use the PAUSE statement to set a breakpoint. Let's use the example program from the last 
section. Here is another listing of the program for convenience: 

100 DIM Arg$ [100] ,Result$ [100] 

110 INTEGER BeginPos.EndPos 

120 ! 

130 Arg$=" Text " 

140 DISP "Arg$=(" ;Arg$;") " , "LEN=" ;LEN(Arg$) 

150 GOSUB Trim 

160 DISP "Result$=("; Result$;") " , "LEN=" ;LEN(Result$) 

170 ! 

180 STOP 

200 ! Given string in Arg$, this subroutine 
210 ! trims leading and trailing blanks . 
220 ! Trimmed string is returned in Result$. 

240 Trim: 

250 BeginPos=0 

260 TrimFront: BeginPos=BeginPos+l 

270 IF BeginPos>LEN(Arg$) THEN Result$="" @ RETURN 

280 IF Arg$[BeginPos,BeginPos]=" " THEN TrimFront 

290 ! 

300 EndPos=LEN(Arg$)+l 

310 TrimEnd: EndPos=EndPos-l 

320 IF Arg$[EndPos,EndPos]=" " THEN TrimEnd 

330 ! 

340 Result$=Arg$ [BeginPos , EndPos] 

350 ! 

360 RETURN 

(If you still have a TRACE on line 255 and NORMAL on line 285 from a previous example, then 
you may want to delete these lines now.) 

Insert this statement into the program: 
245 PAUSE @ DISP "Breakpoint 1" 

Now run the program. It will display the message Breakpoint 1 and then pause. 
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You can do any of several things at this point: 

• Start tracing variables or program flow. 

• Examine or change the value of variables. 

• Execute statements or commands. 

• Resume execution by executing the CONT (continue) command. 

• Single-step the program. 

Tracing operations were explained in the preceding section. Subsequent sections explain the 
latter four topics. 

Accessing Variables from the Keyboard 

One of the pleasing characteristics of Technical BASIC system is that you can access variables 
from the keyboard any time that it is in the "paused" state. You can also change variable's 
values from the keyboard. Note, however, that you cannot access another variables in another 
context; for instance, you cannot access the main program's variables while in a subprogram. 

You can determine the current value of a variable (in the current context) by typing its name 
on a blank line and then pressing the carriage return key: 

BeginPos 

The system responds with: 


You can also perform calculations, such as: 
LEN(Arg$) 

The system responds: 



You can also assign a new value to a variable. For example, to assign a value of 5 to the 
variable named BeginPos, execute: 

LET BeginPos=5 

Now examine the variable by typing: 
BeginPos 
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It will return: 
5 

If you had typed this instead: 
BeginPos=5 

You would have gotten this response: 



because BeginPos=5 is a boolean expression whose value is "false" (since BeginPos is not equal 
to 5); the system represents a false condition with a 0, while a boolean true is represented by a 
1. 

Note also that you can create a variable from the keyboard by assigning it a value: 
LET NewVariable=6.023 

You can use this variable in subsequent keyboard operations. 

NewVariable-1 

5.023 
NewVariable>0 

1 

Executing Commands and Statements 

You can also issue commands while a program is paused. For instance, you can examine the 
catalog of a directory, list the program to a printer, and turn the graphics or alpha displays on 
and off. 

Continuing Program Execution 

When the program is in a paused state, you can continue program execution with the CONT 
command. Program execution then resumes normally, or in the trace mode that was in effect at 
the time the program was paused. 

Preceding paragraphs declared that you can execute nearly all commands from the keyboard 
while a program is paused. You can also add, modify, or delete program lines, or attempt to 
alter the control structures of the program; however, the program cannot be continued after 
such modifications. You will have to pre-run 1 the program (using INIT) or execute RUN. 



Pre-run is described in the "Program Structure and Flow" chapter. 
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Single-Stepping a Program 

One of the most powerful debugging tools available is the capability of single-stepping a program 
— executing it one line at a time. This process allows you to access variables before or after 
each line of a program is executed. 

Single-stepping is performed with the SINGLESTEP command. There are two prerequisites to 
using this command: 

• The program must have been "pre-run" by executing INIT or RUN. 

• The program must be in the paused state. 

Type in the following example, execute an INIT command, and then begin single-stepping by 
executing the SINGLESTEP command three or four times. (If you typed in the preceding example 
program, then you will probably want to store it now, because you will be using it again in the 
next section.) 

100 OPTION BASE 1 

110 REAL Array (5) .Array Sum 

120 INTEGER Indx 

130 ! 

140 ! Enter five numbers, and calculate their sum. 

150 ArraySum=0 

160 FOR Indx=l TO 5 

170 DISP "Enter numeric value #";Indx 

180 INPUT Array (Indx) 

190 ArraySum=ArraySum+Array(Indx) 

200 NEXT Indx 

210 ! 

220 ! Display input data and sum. 

230 DISP "Array:" 

240 MAT PRINT Array; 

250 PRINT "Sum of array elements :" .ArraySum 

260 ! 

270 END 

Notice that it is difficult to tell which program line is being executed without using the TRACE 
ALL command. 

As you can see from the TRACE ALL results, the SINGLESTEP command executes a program line 
and then increments the program counter to the next program line. Thus, SINGLESTEP steps 
through every program line, including those containing non-executed statements like OPTION 
BASE , REAL , INTEGER, and ! comments (which are handled during pre-run and cause no action 
during program execution). 
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As you single-step through the program, you can check variables' contents to see how they 
change. You can also change them as desired to create and test special conditions. 

If the program is in an INPUT or LINPUT statement, then SINGLESTEP is sufficient to terminate the 
operation. After executing SINGLESTEP on one of these input statements, you must first enter 
the expected data from the keyboard and then terminate it with a carriage return. Executing a 
subsequent SINGLESTEP then will execute the following line. 



Software Testing 

In general, testing a program involves verifying that it does work without errors. So in order 
to test a program, you will ordinarily use it across its normal range of conditions. In addition, 
you will often want to ensure that it will not crash when asked by a user to operate outside this 
range. 

There are many methods of testing; they range from testing segments individually to testing the 
entire program as a whole. Although the subject of software testing is extensive, it is mentioned 
here to make sure that you are aware of the need for testing and to help you realize that there 
are many texts available that describe methodical approaches to testing. 

Despite the gamut of available testing methods, here are some approaches that are common to 
most methods: 

• It is difficult to thoroughly test your own programs. It is best to have someone else test 
code that you have written. 

• Question assumptions. For instance, you may assume falsely that the user will not input 
string data when numeric data is expected. 

• Determine boundary conditions for valid inputs, and test each one. For instance, if you 
are expecting a string of up to 20 characters, test your software for strings with lengths 
and 20 (maybe even 21). 

• Check every local branch in the code to make sure that each will be executed properly in 
all directions. Then globally make a test case for each unique path through the program. 

• Check to see if there are any sensitivities to any particular data patterns. 

The "Error Handling" and "Communicating with the Operator" chapters also discuss anticipating 
and handling erroneous inputs. 
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Testing the Example Program 

Using the program presented earlier in this chapter, you can get a feel for implementing some 
of the suggestions shown above. Here is the program again. 

100 DIM Arg$ [100] ,Result$ [100] 
110 INTEGER BeginPos.EndPos 



180 STOP 

200 ! Given string in Arg$ , this subroutine 
210 ! trims leading and trailing blanks . 
220 ! Trimmed string is returned in Result$ . 

240 Trim: 

250 BeginPos=0 

260 TrimFront: BeginPos=BeginPos+l 

270 IF BeginPos>LEN(Arg$) THEN Result $="" @ RETURN 

280 IF Arg$[BeginPos,BeginPos]=" " THEN TrimFront 

290 ! 

300 EndPos=LEN(Arg$)+l 

310 TrimEnd: EndPos=EndPos-l 

320 IF Arg$[EndPos,EndPos]=" " THEN TrimEnd 

330 ! 

340 Result$=Arg$ [BeginPos , EndPos] 

350 ! 

360 RETURN 

Since you didn't write this program, you qualify as a candidate for testing it. 

Some assumptions that you may question are as follows: 

• Will the input always be less than 100 characters? 

• Is it acceptable to leave leading or trailing, non-printing control characters, such as CHR$(0) . 
in the string? or is the program to remove them before removing the spaces? 

• Is a string of length acceptable? or should it generate an error message? 
Boundary conditions for the routine are strings of length 0, 100, and 101. 
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There are three, two-way branches in the program. From studying the permutations of possible 
branch combinations, there are six unique, valid paths through the code (some of the possible 
paths are identical 1 ). Here are the cases that test these paths: 

1. Null Arg$ (LEN=0) with no leading or trailing spaces. 

2. Null Arg$ with leading and trailing spaces. 

3. Non-null Arg$ with leading spaces. 

4. Non-null Arg$ with no leading or trailing spaces. 

5. Non-null Arg$ with trailing spaces. 

6. Non-null Arg$ with both leading and trailing spaces. 

There seem to be no sensitivities to particular data patterns. However, note that the case of the 
non-printing control character embedded in leading or trailing spaces may fit into this category. 

This listing shows testing the routine with the five cases shown above. 

100 DIM Arg$ [100] , Result$ [100] 
110 INTEGER BeginPos.EndPos 

120 ! 

121 Arg$="" 
" Arg$= ( " ; Arg$ ; " ) " , " LEN= " ; LEN ( Arg$ ) 

Trim 
l, Result$=("; Result$;") " , "LEN=" ;LEN(Result$) 



122 DISP 

123 GOSUB 

124 DISP 

125 ! 

126 Arg$= 

127 DISP 

128 GOSUB 

129 DISP 

130 ! 

131 Arg$= 

132 DISP 

133 GOSUB 

134 DISP 

135 ! 

136 Arg$= 

137 DISP 

138 GOSUB 

139 DISP 

140 ! 

141 Arg$= 

142 DISP 



'Arg$=(";Arg$;") 
Trim 
, Result$=(";Result$;") 



" ,"LEN=" ;LEN(Arg$) 

,, ,"LEN="; LEN (ResultS) 



!#*1?" 

1 Arg$= ( " ; Arg$ ; " ) " , " LEN= " ; LEN ( Arg$ ) 
Trim 
, Result$=(" ; ResultS ; ") " , "LEN=" ; LEN (ResultS) 



: ; ;«==»??" 

, Arg$=(" ;Arg$;") 
Trim 
'Result$=( M ; ResultS;") 



","LEN=";LEN(Arg$) 

","LEN="; LEN (ResultS) 



r.'aO 

, Arg$=(" ;Arg$;") 



" ,"LEN=" ;LEN(Arg$) 



143 GOSUB Trim 



Some identical combinations are: 1. Only leading spaces and null Arg$ (LEN=0) or Arg$ is all spaces; 2. Only trailing spaces and null 
Arg$; 3. Both leading and trailing spaces and null Arg$. 
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144 DISP "Result$=("; Result$;") " , "LEN=" ;LEN(Result$) 

145 ! 

146 Arg$=" Two Words " 

147 DISP "Arg$=(" ;Arg$; M ) " , "LEN=" ;LEN(Arg$) 

148 GOSUB Trim 

149 DISP "Result$=(" ;Result$;") " , "LEN=" ;LEN(Result$) 

150 ! 
180 STOP 

200 ! Given string in Arg$ , this subroutine 
210 ! trims leading and trailing blanks . 
220 ! Trimmed string is returned in Result$ . 

240 Trim: 

250 BeginPos=0 

TrimFront: BeginPos=BeginPos+l 

IF BeginPos>LEN(Arg$) THEN Result$="" @ RETURN 
IF Arg$[BeginPos,BeginPos]=" " THEN TrimFront 



260 

270 

280 

290 

300 

310 

320 

330 

340 

350 ! 

360 RETURN 



EndPos=LEN(Arg$)+l 
TrimEnd: EndPos=EndPos-l 

IF Arg$[EndPos,EndPos]=" " THEN TrimEnd 

! 

Result$=Arg$ [BeginPos .EndPos] 



Here are the results of running this test program (without tracing). 



Arg$=() 
Result$=() 
Arg$=( ) 
Result$=() 
Arg$=( !#*1?) 



Result$=( 
Arg$=(::; 
Result$=( 



!#*1?) 
;«==»??) 

: ; ;«==»??) 
'_'aO ) 
Result$=(@A~_'aO) 
Arg$=( Two Words ) 
Result$=(Two Words) 



LEN= 
LEN= 
LEN= 8 
LEN= 
LEN= 8 
LEN= 5 



LEN= 12 
LEN= 12 
LEN= 12 
LEN= 8 
LEN= 12 
LEN= 9 



Note that several different characters were used in several of the tests. This may help show that 
the display device has no data sensitivities. Also note that only the last test tried using spaces 
embedded in the argument. This illustrates that testing almost never stops. 
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Storing 11-6 
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ASSIGN* 11-13, 11-18, 11-20, 11-23, 11-25, 11-26 
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Array variables 4-27 
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Variables 4-2 

Assumptions, questioning 8-18 

ATN 4-17 

ATN2 4-17 

Audio messages 9-4 

AWRIT 9-8, 9-11 

AXES 15-19 
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BackSpace key 9-30 

BASIC editor 2-14, 2-20 

BASIC/DATA files 6-13, 11-12 

BASIC/GRAF file 15-73 

BASIC/PROG files 6-13, 6-14 

BASIC/SUBP files 6-14, 6-16 

BEEP 2-8, 9-4 

BINAND 4-14 
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C 12-1 

FORTRAN 14-1 
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Programs 2-11 

BINCMP 4-14 
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BIT 4-14 
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Blocks 11-16 
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BPLOT 15-69 
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Event-initiated 3-24 

BREAD 15-69 

Break key 9-24, 9-28 

Breaking programs up 3-30 
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BTD 4-16 
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Buffer number 11-12 

Bugs: 
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Bulleted lists 1-6 
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C 

C binaries: 

Compiling 12-3, 12-7, 12-8 

Error trapping 12-6 

File I/O 12-5, 12-19 

Introduction 12-1 

Linking 12-3, 12-7, 12-8 

makebin_c script 12-7, 12-8 
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Passing by reference 12-10 
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Characteristics of COM 6-28 
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COM 3-30, 4-26, 5-2, 6-27, 6-33 
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Communication: 
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Compiling FORTRAN binaries 14-3, 14-8 

Compiling Pascal binaries 13-3, 13-8 

Computer/human interface 9-1 

CON 4-33 
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Branching 3-12 

Execution 3-10 

GOTO 3-12 
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Matrices 4-40 

Numeric 4-5 

Constructs, nesting 3-14 

CONT 3-5, 8-15, 9-25 
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Control: 
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Time and date 10-3 
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Copying: 

Program segments 2-20 

Subarrays 4-43 

COS 4-18 

COT 4-18 

CREATE 6-35, 9-6, 11-12, 11-14, 11-25 

CROSS 4-62 

Cross: 

Product 4-62 

References 8-5 

CRT IS 6-35, 9-6 

CSC 4-18 

CSIZE 15-65 

CSUM 4-54 
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CURSCOL 9-11 

CURSOR 15-52, 15-80 
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Positioning 9-10 

Turning on 9-12 

CURSROW 9-11 
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DATA 3-34, 4-39, 11-4 
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Files 11-9 
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Pointer, moving 11-8 

Structures 2-2, 2-6 

Types 2-10, 4-3, 11-24, 11-28 

Date 10-2 

DATE 10-2 

DATE$ 10-2 
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Debugging: 

Methods 8-4 

Programs 2-3, 2-24 



Decisions 3-1 

Declarations: 

Implicit 4-4 

Of function parameters 6-7 

Declaring: 
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DEG 4-17, 6-35, 15-63, 15-67 
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Dimensioned length, string 5-2 
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DIRECTORY 6-11, 6-12, 6-17 

Disabling keys 9-30 

DISP 2-8, 9-6, 9-10, 9-12 
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DISP USING 4-31 
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Screen 9-6 
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DT0$ 4-15 

DTR 4-18 
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e 
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Field specifiers 9-17 

File access: 

Random . 11-24, .11-26 

Serial . . . ] 11-11 

text/data 11-31 

File I/O: 

C binaries 12-5, 12-19 

FORTRAN binaries 14-6, 14-22 

Pascal binaries 13-6, 13-24 

File: 

ASCII 2-23 

BASIC/DATA 6-13 

BASIC/GRAF 15-73 

BASIC/PROG 6-13, 6-14 

BASIC/SUBP 6-14, 6-16 

Buffers 11-18 

Closing 11-12, 11-31 

Data types 1 1-28 

Names 6-14 

Opening 11-31 

Overhead 11-17 

Pointer 11-18 

Selector 9-6, 9-13 

Size calculations 11-14 

text/data 11-31, 12-5, 13-6, 14-6, 14-22 

FINDPROG 6-11, 6-13 

f _init subroutine 14-4 

FLAG . 6-31, 6-35 

Flags, system 6-30 

FLIP , 6-35 

FLOOR 4-20 

FN END 3-34 

FNORM 4-71 

Formal parameters 6-4, 12-2, 13-2, 14-2 

Formatted printing 9-15 

FOR. .NEXT 3-18 



FORTRAN binaries: 

Compiling 14-3, 14-8 

Error trapping 14-7 

File I/O 14-6, 14-22 

Introduction 14-1 

Linking 14-3, 14-8 

makebin_c script 14-8, 14-9 

Maximum number of 14-6 

Parameter matching 14-5 

Parameter passing 14-10 

Passing by reference 14-10 

Passing by value 14-10 

Restrictions 14-6 

String length 14-18 

FORTRAN programs 14-2 

FORTRAN SUBROUTINES 14-2 

FP 4-20 

Froebenius norm 4-72 

Functions: 

Binary 4-14 

C 12-2 

Constant 6-3 

Data-type declarations 6-7 

Limitations of user-defined 6-7 

Local variables 6-5 

Misc. array 4-71 

Misc. numeric 4-20 

Multi-line 6-5 

Passing parameters to 6-4 

Resident 2-11 

Resident trig 4-17 

Step 4-10 

String 5-9, 5-14 

Timer 10-9 

User-defined 2-11, 5-16, 6-1, 6-2 



g 



GCLEAR 9-9, 15-3 
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